mak-ide 0.1.0__tar.gz

mak_ide-0.1.0/.gitignore

@@ -0,0 +1,119 @@
+# =============================================================================
+# MAKu Microcontroller - ignored files
+#
+# Rule of thumb: everything here is REGENERATED by scripts/ from the sources in
+# rtl/, simulation/, constraints/ and software/. Nothing that is ignored should
+# ever be needed to rebuild the design.
+#   - the Vivado project comes from scripts/create_project.tcl
+#   - the simulation library comes from scripts/run_all_tests.ps1
+# =============================================================================
+
+# --- Vivado project (fully generated by scripts/create_project.tcl) ---
+vivado/
+*.xpr
+*.jou
+*.str
+*.wdb
+*.wcfg
+*.pb
+.Xil/
+.srcs/
+.runs/
+.cache/
+.hw/
+.ip_user_files/
+.sim/
+*.backup.jou
+*.backup.log
+
+# --- Vivado / XSim logs and intermediates ---
+vivado.log
+vivado_*.log
+xsim.dir/
+xsim.log
+xsim.jou
+xsim_*.log
+xsim_*.jou
+xvlog.log
+xvlog.pb
+xvlog_*.log
+xelab.log
+xelab.pb
+xelab_*.log
+flash_*.log
+xsc.log
+xsim.covdb/
+webtalk*.jou
+webtalk*.log
+webtalk*.backup.jou
+webtalk*.backup.log
+
+# --- Synthesis / implementation outputs ---
+*.dcp
+*.bit
+*.bin
+*.ltx
+*.rpt
+*.edn
+*.mmi
+usage_statistics_webtalk.*
+tight_setup_hold_pins.txt
+
+# --- Vivado IP / block design generated output ---
+*.gen/
+*.hbs
+hd_visual/
+incrCheckPhaseSaveFP.dcp
+
+# --- Editor / OS noise ---
+.DS_Store
+Thumbs.db
+desktop.ini
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+
+# --- Scratch ---
+scratch/
+tmp/
+*.tmp
+
+# regression-runner lock
+.maku_test.lock
+
+# --- Python bytecode from software/ tooling ---
+__pycache__/
+*.pyc
+impl_*.log
+cp_*.log
+
+# per-test durations, written by run_all_tests.ps1 for longest-first scheduling
+.maku_test_times.json
+
+impl_*.log
+impl_*_console.log
+prog_*.log
+prog_*.jou
+impl_*.jou
+suite_*.log
+mut_*.log
+soak_*.log
+partition_*.log
+g?.log
+gate*.log
+create_proj*.log
+*.jou
+sweep_*.log
+software/_sweep_*
+
+# mutation campaign leftovers - a run must not dirty the tree
+mutation_results_*.txt
+*.campaign_backup
+
+# The IDE's virtualenv. It is a build artefact with absolute paths baked into
+# it - and `~/.config/maku/credentials.toml` lives OUTSIDE the tree for the
+# same reason maku.toml may not hold a key (spec 13.5).
+tools/maku-tui/.venv/
+tools/maku-tui/**/__pycache__/

mak_ide-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Manikanta Gonugondla
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mak_ide-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.5
+Name: mak-ide
+Version: 0.1.0
+Summary: An instrument workbench for the MAK8u dual-core microcontroller
+Project-URL: Homepage, https://github.com/Manikanta25055/MAK8u
+Project-URL: Source, https://github.com/Manikanta25055/MAK8u/tree/main/tools/maku-tui
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyserial>=3.5
+Requires-Dist: textual<1.0,>=0.79
+Provides-Extra: assistant
+Requires-Dist: openai>=1.40; extra == 'assistant'
+Description-Content-Type: text/markdown
+
+# MAK IDE
+
+An instrument workbench for the **MAK8u**, a dual-core deterministic
+microcontroller on a Nexys A7 (Artix-7). It runs in a terminal.
+
+```
+mak
+```
+
+---
+
+## Read this first: there is no debugger, and there cannot be one
+
+The obvious ask for a microcontroller IDE is Keil, and Keil's value is
+overwhelmingly its **debugger** — halt the core, single-step, set a breakpoint,
+watch registers and memory live.
+
+> **The MAK8u has no debug interface.** There is no halt, no single-step, no
+> breakpoint, no register readback, and no way for the host to read target
+> memory. The only host-to-target channel is one UART.
+
+That is the hardware as built, not a gap in this tool. A tool that implied
+otherwise would be promising a product that cannot exist on this silicon.
+
+What the machine does offer, and what this workbench is built on:
+
+| channel | direction | carries |
+|---|---|---|
+| UART bootloader protocol | host → target | a whole program image, magic-framed and checksummed |
+| UART, program-driven | target → host | whatever the running program chooses to transmit |
+| 16 LEDs | target → eye | heartbeats, lock, reset, per-core retire, error stickies |
+| 8-digit seven-segment | target → eye | one of eight values, selected by `sw[5:3]` |
+| `sw[7]`, `sw[6]` | hand → target | boot-witness probe; priming defeat |
+| boot witness | target → program | what the flash reader saw, readable only *by a program on the target* |
+
+**Every observation of internal state is made by a program you load.** The host
+never reads the machine; it reads what a program on the machine says. So this is
+an instrument workbench, not a debugger — which turns out to suit the device,
+because its whole method is purpose-built witness images.
+
+---
+
+## What works
+
+| feature | state |
+|---|---|
+| Editor with live assembler diagnostics | **works** — line and, where the assembler quotes a token, column |
+| Build to a `.mem` image | **works** |
+| Image inspector and disassembler | **works** — what is at word N, and which source line put it there |
+| Load over UART, run, monitor | **works** — hex/ascii, pause, save log |
+| Instruments pane, seventeen `read_*_hw.py` readers | **works**, one command each, globbed from disk |
+| Boot-witness reader | **works** — refuses a short dump rather than decoding it |
+| Self-boot regression checklist | **works** — and reports INCONCLUSIVE, never green, on a one-sided run |
+| Command line, three layout modes | **works** — `/` lists everything, by name |
+| Program the FPGA or its flash from macOS | **not shipped** — see below |
+| RTL regression suite | **impossible here** — Vivado has no macOS build |
+| Source-level debugger | **impossible** — see above |
+| Assistant pane | **works** — NVIDIA NIM, grounded in the repository, citing every fact |
+| Project window, file operations, documentation panel | **works** |
+
+### What it looks like
+
+Work mode, with the assembler's verdict under the token it quoted — `R9` is
+not a register this machine has:
+
+![Work mode: the editor, the explorer, and one diagnostic](docs/work.svg)
+
+`/` on its own, listing every command this project has, including one per
+`read_*_hw.py` found on disk:
+
+![The command line, open and listing](docs/commands.svg)
+
+The Welcome screen:
+
+![The Welcome screen: recent projects, documentation, the port](docs/welcome.svg)
+
+These are exported from a real run of the app, not drawn by hand, by
+`docs/screenshots.py` — and `tests/test_screenshots.py` re-renders them and
+fails when the app stops drawing what they show. A screenshot is the one claim
+in a repository that rots without anyone noticing, because a picture cannot
+fail a test.
+
+### Programming the board
+
+Flashing is **not part of this tool on macOS**. Vivado has no macOS build, and
+while `openFPGALoader` exists and installs cleanly, this checkout has never
+programmed a board with it. Bitstreams are built on the Windows box, and
+`*.bit` is not committed. Treat macOS flashing as unproven until there is a
+measurement saying otherwise.
+
+The board **boots from its own flash**, so day-to-day work needs no programming
+at all: load an image over UART and run it.
+
+---
+
+## Install
+
+**The command is `mak`. The distribution is `mak-ide`** — `mak` on PyPI is an
+unrelated package, and a console script's name is independent of the
+distribution that installs it.
+
+**Not published yet.** `.github/workflows/release.yaml` builds, checks and
+installs the wheel on every push, and uploads only from a manual run with the
+word `publish` typed into it. Until that is fired, the four commands below
+will not resolve; the two after them work today from a clone.
+
+### Once it is published
+
+```bash
+uv tool install mak-ide       # recommended: isolated, one command on PATH
+pipx install mak-ide          # the same thing, if you already use pipx
+pip install mak-ide           # only inside a virtualenv you already manage
+```
+
+macOS and Linux, in one line:
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/Manikanta25055/MAK8u/mak-ide/tools/maku-tui/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/Manikanta25055/MAK8u/mak-ide/tools/maku-tui/install.ps1 | iex
+```
+
+Both scripts find `uv` or install it, run `uv tool install mak-ide`, and tell
+you if the directory they installed into is not on your `PATH` — rather than
+leaving you with a command that "did not install". Neither needs `sudo` or
+administrator rights. `uv tool uninstall mak-ide` undoes either.
+
+**The one-liners fetch from a URL, and this repository is private.** They
+return 404 for anyone who cannot read it, including you on a machine without
+credentials, until the repository is public.
+
+**The URLs name the `mak-ide` branch, not `main`,** because that is where
+`install.sh` and `install.ps1` actually are — the default branch has no
+`tools/` directory yet. They move to `main` when that branch merges.
+
+`mak --version` says which one you have. `mak --doctor` says why it will not
+start.
+
+### From a clone, today
+
+Pick the path that matches what you are doing — they give you two different
+things and the difference is the point.
+
+### To use it
+
+```bash
+uv tool install ./tools/maku-tui
+```
+
+or, equivalently:
+
+```bash
+pipx install ./tools/maku-tui
+```
+
+Either one puts **`mak`** on your `PATH` — one command, not three. Both were
+verified on this checkout — `uv` on Python 3.13, `pipx` on 3.14. This is an ordinary
+wheel install: **source edits need a reinstall**, which is what installing
+means. The NIM assistant is an extra and is left out unless you ask:
+
+```bash
+uv tool install "./tools/maku-tui[assistant]"
+```
+
+### To work on it
+
+```bash
+cd tools/maku-tui && python3 -m venv .venv && .venv/bin/pip install -e .
+ln -s "$PWD/bin/mak" ~/.local/bin/mak
+```
+
+`bin/mak` is a shell script, not a generated console entry point, and it
+resolves through however many symlinks put it on `PATH` back to this checkout
+and its virtualenv. So **a source edit is live the next time `mak` starts**,
+and there is nothing to reinstall. That is why the developer path exists at
+all.
+
+`mak` runs in whatever directory you start it from and finds that project's
+`maku.toml` by searching upward, the way `git` finds a repository.
+
+### If `mak` will not start
+
+```bash
+mak --doctor
+```
+
+It works on both installs and reports which one it is looking at; `mak --where`
+prints the checkout, or the installed package when there is no checkout.
+
+On **this** tree the usual cause is not a broken package. Every `.pth` file in
+a venv under `~/Desktop` acquires the macOS `UF_HIDDEN` flag, and Python 3.13
+**skips hidden `.pth` files** — so an editable install that `pip` reports as
+installed is inert, and the symptom is `No module named maku_tui`. `chflags
+nohidden` works and does not hold. The fix that holds is a symlink from
+site-packages into `src/`, and `--doctor` prints it. Nothing outside that
+situation needs the symlink, and the doctor says so rather than reporting a
+fault.
+
+---
+
+## Using it
+
+**There are no keyboard shortcuts, and that is deliberate.** There were
+twenty-one. Ctrl bindings needed a modifier some terminals do not deliver,
+F-keys carried actions nobody could discover, and one of them — `ctrl+i` —
+could never fire at all, because 0x09 *is* the tab character. That binding
+validated, appeared in the key bar and in the palette, and did nothing, for as
+long as it existed. Automated tests could not see it either: a pilot presses
+keys by name, so a binding no terminal can send passes every one of them.
+
+Nine keys remain, and all nine are navigation:
+
+| key | does |
+|---|---|
+| `/` | open the command line — every action is here, by name |
+| arrows | move between sections, or move the caret inside the editor |
+| `tab` / `shift+tab` | next / previous section, in reading order |
+| `enter` | activate what has focus — open a file, enter edit mode, answer a question |
+| `esc` | close what is open, one layer at a time: a question, the command line, edit mode |
+
+Anything else is typed on the command line. `/` on its own lists every command
+this project has, including one per `read_*_hw.py` on disk, and an argument is
+completed from the kind it declares — `/load ` offers `.mem` images and nothing
+else. **An argument that does not resolve is refused with a reason and your
+text is kept**, never rounded to the nearest plausible file.
+
+A few worth knowing:
+
+| command | does |
+|---|---|
+| `/open` `/save` `/build` `/load` | the working loop |
+| `/new` `/newfolder` `/rename` `/delete` | files; `/delete` asks first |
+| `/key` | store the NVIDIA NIM key for the assistant, in a masked field |
+| `/witness` `/self-boot` | read the boot witness; run the regression |
+| `/focus` `/work` `/bench` | the three layouts |
+
+### The mouse
+
+Click to focus a pane; click a line in the editor to put the caret there;
+click a folder in the explorer to open or shut it. The wheel scrolls whatever
+is under the pointer, not whatever had focus last. While a question is open it
+owns the pointer as well as the keyboard — a click outside the box does not
+focus what is behind it.
+
+### The key is never echoed
+
+`/key` opens a field that is drawn as dots. The characters never enter the
+drawing path at all, so the masking is not an overlay a redraw could get
+wrong. The key is written to `~/.config/maku/credentials.toml` at mode 0600 in
+a 0700 directory, with the mode set as the file is created rather than
+tightened afterwards, and it is **never** written to `maku.toml`, which is
+committed. `/key clear` removes it.
+
+---
+
+## Testing
+
+```bash
+tools/maku-tui/.venv/bin/python tools/maku-tui/tests/run_all.py
+```
+
+One `PASS`/`FAIL` per file and a single `RESULT:` line. A suite with no
+`RESULT:` line reads as unverified, and this one has none such. A check that
+cannot be *built* on the platform it is running on — there is one, and it needs
+the macOS hidden-flag — reports `SKIP` with its reason, and `run_all.py` lifts
+those lines into its own output so a check cannot stop running quietly.
+
+`.github/workflows/maku-tui.yml` runs all of it on macOS and Linux, on Python
+3.11 and 3.13. Linux is there for a reason rather than for symmetry: the
+hidden-`.pth` failure this tool works around is a macOS behaviour, so Linux is
+where a check that quietly depends on the workaround shows up.
+
+Three gates are not in `run_all.py`. Two need the board —
+`gate_eight_images.py` and `gate_witness.py` — and one needs a real terminal:
+
+```bash
+tools/maku-tui/.venv/bin/python tools/maku-tui/tests/gate_pty.py
+```
+
+`gate_pty.py` forks a pseudo-terminal and sends **bytes**. Textual's test
+pilot presses keys *by name*, which is why `ctrl+i` survived a suite that was
+green — no terminal can send it, and a pilot does not have to. It is also why a
+key that was handled twice, once by the router and once by its binding, passed
+everything: no test asked what happens when the bytes for `/` arrive while the
+command line is open. The answer was that the line re-opened at that character,
+so **no path argument could be typed at all**. The gate asserts what is on the
+wire, including the one property that is only meaningful there: the NIM key
+never appears in the byte stream.
+
+---
+
+## Licence
+
+**Apache-2.0** — the full text is in [LICENSE](LICENSE). Chosen over MIT for the
+patent grant, and in place before the first public commit rather than after.