hgoblet 0.2.1__tar.gz

hgoblet-0.2.1/LICENSE

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

hgoblet-0.2.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include tests *.py
+recursive-include src/hgoblet py.typed

hgoblet-0.2.1/PKG-INFO

@@ -0,0 +1,444 @@
+Metadata-Version: 2.4
+Name: hgoblet
+Version: 0.2.1
+Summary: hgoblet // one line-only terminal for installed MProcs-family suites (Fumuda-XY, MProcs, Nanuska-GP)
+Author-email: tderk <usvu.tech@gmail.com>
+License-Expression: MIT
+Keywords: mprocs,fumuda-xy,nanuska-gp,terminal,launcher,switchboard,tui,curses
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# hgoblet
+
+**hgoblet** is one line-oriented shell for the MProcs family. It runs the
+shared LPRO terminals inline, switches between the three suites without
+leaving the prompt, and keeps one global username across all of them.
+
+It finds every installed copy of:
+
+| suite | inline alias | language |
+| --- | --- | --- |
+| **Fumuda-XY** | `fxy` *(default)* | Japanese |
+| **MProcs** | `mp` | original / English |
+| **Nanuska-GP** | `ngp` | Russian |
+
+The nine shared LPRO terminals run directly inside the prompt:
+
+`mdcci` · `neonbunny` · `jade-dojo` · `bumerang` · `alokate` ·
+`monk-rpg` · `morning-bell` · `destiny` · `vanilla`
+
+The upstream full-screen terminals — `gwf`, `polyhistor`, `flu0`, and
+`jade-wire` — are not line-portable. They remain available explicitly with
+`--tui`; they are never opened implicitly.
+
+The default is **Jade Dojo** (`Dojical`), not the upstream Morning Bell
+default. Use `hgoblet fn morning-bell` (or type `morning-bell`) when you
+actually want `morn`.
+
+```text
+kredt@minios:~$ hgoblet
+スタ ( zeta ) $ print time
+時刻: 2026-11-03 10:17:55.934541
+
+スタ ( zeta ) $ mp
+ст ( zeta ) $ print time
+Time:  2026-11-03 10:17:55.934541
+
+ст ( zeta ) $ exit
+kredt@minios:~$
+```
+
+All three suites share the same command language, so selecting a suite and a
+function from one prompt is enough:
+
+```bash
+hgoblet                      # directly enter Jade Dojo line terminal
+hgoblet shell                # open hgoblet's command prompt
+hgoblet line mdcci           # enter Medicci Archive inline
+hgoblet fn morning-bell      # enter Morning Bell inline
+hgoblet fn flu0 --tui        # explicit upstream full-screen app
+hgoblet run --tui            # explicit upstream full-screen launcher
+```
+
+## Jade Dojo is the default
+
+The upstream MProcs launchers start on **Morning Bell** (`morn`). hgoblet
+deliberately starts on **Jade Dojo** (`Dojical`) instead.
+
+Use `hgoblet fn morning-bell` (or type `morning-bell` in the prompt) when you
+actually want `morn`.
+
+## Install
+
+```bash
+cd BDCS/hgoblet
+python3 -m pip install .
+# or, on a PEP 668 managed system:
+python3 -m pip install --break-system-packages .
+# or isolated:
+pipx install .
+```
+
+This installs three commands:
+
+- `hgoblet` — the line-only terminal (directly opens the active suite's default)
+- `hgo` — the same entry point
+- `mp` — a friendly short command for MProcs (see below)
+
+Requirements: Python 3.8+. A curses-capable terminal is only required for
+`hgoblet tui` and the explicitly opted-in full-screen apps. No runtime
+dependencies.
+
+## Quick start
+
+```bash
+hgoblet                 # directly open the line-only default terminal
+hgoblet shell           # open hgoblet's own command prompt
+hgoblet tui             # open the upstream full-screen switchboard
+hgoblet detect          # list every installation found
+hgoblet status          # active suite + installation summary
+hgoblet shift           # rotate fumuda -> mprocs -> nanuska -> fumuda
+hgoblet use ngp         # make Nanuska-GP active
+hgoblet line            # enter line-only Jade Dojo
+hgoblet line mdcci      # enter Medicci Archive inline
+hgoblet run             # same as `hgoblet line` (Jade Dojo)
+hgoblet run --tui       # open the upstream full-screen launcher
+hgoblet functions --all # list line-supported and upstream-only functions
+hgoblet fn polyhistor   # line-error: upstream-only; add --tui to open it
+hgoblet user snowtiger  # set the username used by every suite
+```
+
+Command-specific examples:
+
+```bash
+hgoblet which mprocs                 # /usr/bin/MProcs  (or the real path)
+hgoblet which --plan                 # show hgoblet's launch plans
+hgoblet run nanuska -- -u zeta       # raw-style invocation; records --user
+hgoblet run mprocs --raw             # run MProcs bare
+hgoblet run --tui                    # upstream launcher, Jade Dojo selected
+hgoblet fn --suite fxy mdcci         # enter Fumuda-XY on Medicci Archive
+hgoblet fn --suite ngp flu0 --tui    # open upstream FLU0 explicitly
+hgoblet functions nanuska --json     # machine-readable function list
+hgoblet functions --all --json       # every suite, line availability included
+hgoblet status --json                # machine-readable detection result
+```
+
+## Commands
+
+| command | what it does |
+| --- | --- |
+| `hgoblet` | directly open the line-only default terminal; show status when not interactive |
+| `hgoblet shell` / `terminal` / `repl` / `basic` | open hgoblet's own command prompt |
+| `hgoblet line [function]` / `inline` | enter the line-only runtime for Jade Dojo or one function |
+| `hgoblet tui` / `hub` | open the upstream switchboard TUI explicitly |
+| `hgoblet detect` / `list` / `scan` | find installations (all copies, not just the best one) |
+| `hgoblet status` | active suite, username, and one line per suite |
+| `hgoblet user [name]` / `username` | show or set the global terminal username |
+| `hgoblet use <suite>` | save the active suite (`fumuda`, `mprocs`, `nanuska`, or an alias) |
+| `hgoblet shift [next\|prev\|suite]` | rotate or switch the active suite |
+| `hgoblet which [suite]` | print terminal, focus, enter and line plans; `--plan` included |
+| `hgoblet functions [suite]` / `fns` | list functions and line availability; `--all` shows every suite |
+| `hgoblet fn [function]` / `focus` | enter a function inline; upstream-only functions require `--tui` |
+| `hgoblet run [suite]` | enter the line-only default terminal; `--tui` opens upstream launcher |
+| `hgoblet version` | print the hgoblet version |
+
+`--enter` remains available on `run` and `fn` for compatibility with the
+upstream plans. Upstream full-screen behavior is always explicit: use `--tui`.
+`--raw` runs the bare suite and cannot be combined with `--tui`.
+
+Global JSON is available on `detect`, `status`, `shift`, `which`,
+`functions`, and `user`. `--print` on `run`/`fn` shows the command without
+executing it.
+
+## Upstream TUI keys (explicit opt-in)
+
+These keys apply only to `hgoblet tui`, `hgoblet run --tui`, and
+`hgoblet fn <function> --tui`.
+
+| key | action |
+| --- | --- |
+| `↑` / `↓` | move in the focused pane |
+| `Tab`, `←`, `→` | switch between the suites and functions panes |
+| `Enter` | on a function: enter it directly; on a suite: open its launcher |
+| `e` | enter the selected suite's default terminal (Jade Dojo) |
+| `s` | shift to the next installed suite |
+| `u` | make the highlighted suite active |
+| `r` | rescan the machine |
+| `d` | details for the highlighted suite/function |
+| `?` / `h` | help |
+| `q` | quit |
+
+`Esc` closes an overlay. The footer always shows the most useful keys.
+
+## The line-only terminal
+
+A bare `hgoblet` execs the active suite's line-only default terminal
+directly. It does not print an hgoblet banner, launch a menu, or open a
+full-screen application implicitly. The suite's own prompt is all you see:
+
+```text
+ st ( zeta ) $
+```
+
+The active suite is intentionally not printed next to the prompt. Type `exit`
+to return to your OS shell.
+
+Use `hgoblet shell` when you want hgoblet's own meta-command prompt. It
+provides the same switch and utility commands:
+
+```text
+st ( zeta ) $ fxy        # make Fumuda-XY active
+st ( zeta ) $ mp         # make MProcs active
+st ( zeta ) $ ngp        # make Nanuska-GP active
+st ( zeta ) $ mdcci      # enter Medicci Archive inline
+st ( zeta ) $ fxy mdcci  # select Fumuda-XY and enter Medicci inline
+st ( zeta ) $ mp mdcci   # select MProcs and enter Medicci inline
+st ( zeta ) $ ngp functions
+st ( zeta ) $ enter      # enter Jade Dojo inline
+st ( zeta ) $ all        # list functions for all suites
+st ( zeta ) $ status
+st ( zeta ) $ user polar
+st ( zeta ) $ ! ls -la
+st ( zeta ) $ exit
+```
+
+### Function registry
+
+`functions` shows the active suite. `functions all` (or `all`) shows every
+installed suite and marks each function as `line` or `tui`:
+
+```text
+Fumuda-XY // v10.12.1
+  line 1   mdcci
+  line 2   neonbunny
+  ...
+  tui   f    flu0
+```
+
+Line functions are:
+
+`mdcci`, `neonbunny`, `jade-dojo`, `bumerang`, `alokate`, `monk-rpg`,
+`morning-bell`, `destiny`, `vanilla`.
+
+`gwf`, `polyhistor`, `flu0`, and `jade-wire` remain upstream full-screen
+terminals. Type `fn flu0 --tui` or `hgoblet fn flu0 --tui` to open one
+explicitly.
+
+The three suites expose the same command language, so an installed function is
+available everywhere:
+
+```text
+fxy mdcci     mp mdcci     ngp mdcci
+fxy morning-bell  mp morning-bell  ngp morning-bell
+```
+
+Useful commands:
+
+| command | action |
+| --- | --- |
+| `fumuda-xy` / `fumuda` / `fxy` | make Fumuda-XY active |
+| `mprocs` / `mp` | make MProcs active |
+| `nanuska-gp` / `nanuska` / `ngp` | make Nanuska-GP active |
+| `fxy FUNCTION` / `mp FUNCTION` / `ngp FUNCTION` | select a suite and enter inline |
+| `fxy functions` | list Fumuda-XY's functions |
+| `enter [suite]` / `run [suite]` | enter the suite's line-only Jade Dojo |
+| `fn [function]` / `focus` | enter a line-supported function inline |
+| `functions [filter]` / `fns` | list the active suite; `functions all` lists all suites |
+| `all` | shorthand for `functions all` |
+| `tui [suite]` / `menu [suite]` | explicitly open the upstream full-screen launcher |
+| `status` / `st` | active suite, username, and installations |
+| `suites` / `list` / `ls` | list suites and inline aliases |
+| `which [suite]` | show raw, focus, enter and line plans |
+| `detect` / `scan` / `refresh` | rescan the machine |
+| `shift [next\|prev]` | rotate the active suite |
+| `use <suite>` | another way to switch the active suite |
+| `user [name]` / `username` | show or set the global username |
+| `cd <dir>` / `pwd` | change directory |
+| `! <command>` | run a shell command |
+| `help` / `?` | show help |
+| `exit` / `quit` / `q` | leave hgoblet's prompt (or the direct terminal) |
+
+`switch` is deliberately left to the suites themselves (their recording /
+passive-terminal switch). In hgoblet's prompt and inside a line terminal,
+switch suites with the aliases above.
+
+### One username everywhere
+
+The username is global. Setting it in one place changes it for hgoblet and for
+every suite launched afterwards:
+
+```bash
+hgoblet user snowtiger
+```
+
+Inside the basic terminal, `user snowtiger` does the same. Inside a suite,
+`user snowtiger` or `username snowtiger` is recorded back to hgoblet, so the
+next suite prompt and the basic terminal prompt both show `snowtiger`. The
+value is stored in hgoblet's config and passed to each suite through
+`HGOBLET_USERNAME`. An explicit `-u` / `--user` flag on `hgoblet run`,
+`hgoblet fn`, or `mp` also updates the global username. `--raw` still runs
+the bare command without hgoblet's in-terminal alias hook, but an explicit
+`--user` value is recorded globally.
+
+`change username <name>` is also accepted. hgoblet normalizes it before
+handing it to the suite because upstream's multi-word parser otherwise reads
+the literal word `username` as the new name.
+
+## Switching from inside a terminal
+
+Once a suite's line runtime was opened through hgoblet (`line`, `run`,
+`fn`, `mp`, or a suite-prefixed function), type one of these aliases at its
+prompt and press Enter:
+
+```text
+fumuda-xy   fumuda   fxy     -> Fumuda-XY (Japanese)
+mprocs      mp               -> MProcs (English)
+nanuska-gp  nanuska  ngp     -> Nanuska-GP (Russian)
+```
+
+The current suite exits and the target suite starts **inside the same terminal
+window**, in the same function. No `[hgoblet]` banner or switch notification is
+printed. The active suite and the current username are recorded in the config.
+Localized aliases such as `FXY`, `MProcs`, `NGP` and `нгп` work too.
+
+hgoblet does **not** take over the suite's own `switch` command: that remains
+the upstream recording/passive-terminal switch. Switching suites uses the
+suite aliases above instead. The alias hook only exists in terminals launched
+by hgoblet; `--raw` deliberately runs the bare command without it. The
+upstream full-screen terminals are opened only when you pass `--tui`.
+
+## How detection works
+
+hgoblet does not import a suite into its own process. It:
+
+1. scans `$PATH`, `~/.local/bin`, `~/bin`, `/usr/local/bin`, `/usr/bin`,
+   `/bin`, Homebrew's bin, common pipx venv bins, and any directory in
+   `HGOBLET_SCAN_PATH`;
+2. looks for each suite's short and long console names (`fxy`, `Fumuda-XY`,
+   `mp`, `mprocs`, `ngp`, `nanuska-gp`, localized aliases, …);
+3. reads the Python interpreter from the command's shebang and asks **that**
+   interpreter for the distribution version and package location;
+4. falls back to `python -m <package>` when a suite is importable in the
+   current interpreter but has no console script;
+5. ignores commands that merely share a name but cannot prove they belong to
+   the suite.
+
+Long aliases are shown as aliases, for example `mp>MProcs` when only the
+capitalized MProcs script exists. Multiple installations of the same suite are
+kept and ranked: short command first, then `$PATH` order.
+
+## How the line runtime works
+
+The nine shared LPRO terminals are launched through a small line bootstrap:
+
+```text
+$XDG_CACHE_HOME/hgoblet/line_bootstrap.py   (usually ~/.cache/hgoblet/)
+```
+
+The bootstrap:
+
+- imports the suite's `lpro` / `lpro_s` command engines;
+- starts with the global username from hgoblet's config;
+- uses the same `st ( user ) $` prompt in every suite;
+- runs the command language directly, without a curses launcher;
+- sets the upstream `morn` swap only for `morning-bell`;
+- intercepts `exit` to return to hgoblet;
+- intercepts suite aliases to switch the active suite inline;
+- records `user`, `username`, and `change username` back to hgoblet.
+
+`gwf`, `polyhistor`, `flu0`, and `jade-wire` are not line-portable upstream
+terminals. `--tui` writes a separate bootstrap:
+
+```text
+$XDG_CACHE_HOME/hgoblet/focus_bootstrap.py
+```
+
+That bootstrap imports the selected suite's own TUI and patches `_default_index`,
+`_main_loop`, and `_make_input` to open or focus one upstream wrapper.
+
+Function names are canonical across suites (`mdcci`, `jade-dojo`,
+`polyhistor`, `flu0`, `jade-wire`, …), while the labels and descriptions come
+from the installed suite, so a Japanese Fumuda-XY and a Russian Nanuska-GP
+are both readable.
+
+## The `mp` shim
+
+`mp` is installed by hgoblet because MProcs' own console script is the
+capitalized `MProcs` on many systems. It is deliberately simple:
+
+- interactive, no arguments: find MProcs, skipping hgoblet's own `mp` script,
+  and open its line-only Jade Dojo terminal;
+- `mp --tui`: explicitly open the upstream full-screen launcher;
+- with other arguments or without a TTY: run MProcs normally, e.g.
+  `mp --version`, `mp --list`, `mp --user zeta`; an explicit `--user`
+  also updates the global username;
+- if MProcs cannot be found: print the install hint and exit 127.
+
+The detector ignores console scripts that contain `hgoblet.cli`, so the shim
+can never select and exec itself.
+
+## Config
+
+The active suite, global username, and recent handoffs are stored in:
+
+```text
+$HGOBLET_CONFIG
+or $XDG_CONFIG_HOME/hgoblet/config.json
+or ~/.config/hgoblet/config.json
+```
+
+Example:
+
+```json
+{
+  "active": "fumuda",
+  "username": "zeta",
+  "history": [
+    {"suite": "nanuska", "function": "polyhistor"},
+    {"suite": "fumuda"}
+  ],
+  "version": 1
+}
+```
+
+A missing or corrupt config falls back to `fumuda` and the username `zeta`.
+Writes are atomic.
+
+## Development
+
+```bash
+cd BDCS/hgoblet
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+Layout:
+
+```text
+src/hgoblet/
+├── catalog.py    # the three suites, aliases, default
+├── model.py      # Installation / Discovery / Function / LaunchPlan
+├── detect.py     # PATH, pipx and interpreter probing
+├── functions.py  # canonical function table + localized probe
+├── launch.py     # terminal / focus / line plans and bootstraps
+├── config.py     # active suite, global username, history
+├── shell.py      # line-only inline terminal and command registry
+├── tui.py        # upstream switchboard TUI (explicit opt-in)
+└── cli.py        # argparse commands
+```
+
+## License
+
+MIT. See `LICENSE`.