Metadata-Version: 2.4
Name: gusher
Version: 1.0.1
Summary: gusher // a minimal phrase-seeded glitch terminal over every MProcs and Fumuda-XY console
Author: tderk
License: MIT
Keywords: terminal,glitch,generative,mprocs,fumuda-xy,ascii
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Artistic Software
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# gusher

**gusher** is the smallest terminal in the BDCS suite. It is a plain prompt — no
TUI, no menus, no screen painting — that turns every phrase you type into a
deterministic, glitched block of hackertech art assembled from the installed
**MProcs** and **Fumuda-XY** consoles.

Open it as:

```bash
gusher
# or
gxr
```

The two commands are the same program.

gusher is also built into every **MProcs** and **Fumuda-XY** terminal (`lpro.py`
and `lpro_s.py`, recording and non-recording modes). Inside those shells the
same names work on one line, and the terminal's current username is used
automatically for `--user`:

```text
gusher -u ghost -n 24 -w 80 "ghost in the wire"
gxr --sources
ガッシャー 長さ 24 幅 80 フレーズ 幽霊
```

MProcs and Fumuda-XY declare `gusher>=1.0.1`, so a normal `pip install` or
upgrade of either suite installs gusher automatically. If gusher is missing
from an older installation, the terminal command offers to install it; use
`gusher --install` (or `--yes`) for an unattended install.

## The one variable

There is exactly one user-facing variable: **user**.

```bash
gusher --user ghost
gxr -u ghost
GUSHER_USER=ghost gusher
```

The prompt is:

```text
ghost@gusher:~$
```

Everything else — phrase, seed, colours, source mix — is derived from that user
and the phrase.

## No bundled content

gusher does **not** ship a dictionary, a corpus, an image, or a theme. The
wheel contains only Python code and this README. At runtime it indexes the
installed suites:

- every readable `data/*.json` and `data/themed/*.json` under `MProcs/` and
  `Fumuda_XY/`;
- every `theme.py` under their `scripts/` and `modules/` trees;
- POLYHISTOR’s content modules (`domains`, `encyclopedia`, `timeline`,
  `almanac`, `people`, `sources`, `lexicon`);
- the uppercase literal lists/dicts in the console content modules
  (`agent.py`, `drills.py`, `ops.py`, `program.py`, `lexicon.py`,
  `ghostwrite.py`, `knowledge.py`, `technica.py`, `app.py`).

The Python content modules are parsed with `ast.literal_eval`; they are **never
executed**, so device, network, and AI code cannot run during indexing. JSON
corpora are loaded lazily, one at a time, with an LRU cache.

On a normal install the index covers hundreds of corpora and nearly three
hundred text pools — English, Japanese, Chinese characters, hangul, katakana,
medical, legal, scientific, intelligence-fiction, JADE//WIRE, FLU0, POLYHISTOR,
proverbs, scriptures, agent dossiers, drills, ghostwrite fragments, rigs,
protocols, missions, sigils, and more.

**Not indexed:** `ai_images` images, log files, README/release notes, `.pyc`
files, and text generated at runtime by functions or AI calls. Those are not
static console data.

Discovery order for each suite:

1. `GUSHER_MPROCS_HOME` / `GUSHER_FUMUDA_HOME` (package dir or project dir);
2. the normal Python import path (`importlib.util.find_spec`);
3. `sys.path` entries;
4. sibling source checkouts next to the project.

Use `gusher --sources` to see what was found:

```text
MProcs     /home/user/.local/lib/python3.13/site-packages/MProcs
Fumuda-XY  /home/user/.local/lib/python3.13/site-packages/Fumuda_XY
indexed: 286 text pools, 281 JSON corpora from 2 provider(s)
```

## If both suites are missing

gusher needs the suites because they are the resource stores. If **both** are
missing it explains the two installs and asks for confirmation:

```text
gusher: neither MProcs nor Fumuda-XY is installed.
Install the two resource providers, then run gusher again:
  python3 -m pip install MProcs Fumuda-XY
...
Install both now? [Y/n]
```

If pip reports `externally-managed-environment`, the prompt offers the usual
retry:

```text
pip reports an externally managed environment.
Retry with --break-system-packages? [y/N]
```

You can also authorize it up front:

```bash
gusher --break-system-packages
gxr --install --yes --break-system-packages
```

`--install` / `--yes` make the install unattended. If only one suite is present
gusher still runs, with a warning that the other half of the source pool is
absent. A non-interactive run never installs anything unless `--install` or
`--yes` is given.

## Phrase seeds

A phrase is the seed. The exact same `(user, phrase)` pair always produces the
exact same block; a different phrase, or a different user, produces a different
one.

```text
seed = blake2b(user + "\0" + phrase)
```

The seed selects the source palette (JSON corpora and theme constants), the
colour set, and every line. Each line gets its own derived seed so the block is
stable but internally varied. Words in the phrase are also matched against
corpus and theme names, so `bible proverb`, `medical blood pressure`, or
`jade wire neon` pull those shelves into the mix before the random fill.

## Output

Default output is **24 lines × 80 columns**. Each phrase prints a one-line seed
header followed by the block:

```text
[4141e8809f8948c9] ghost in the wire | zeta | 14x78 | fp:66a33ead5e15 | MProcs+Fumuda-XY
a service record :: lx - 現場測定で使用される単位
/* Skunk >emon Hybrid % THC - - 19-25% LemOn, Flavvors: Citrus SkuNk, Effects:
シュ :: K - アーカイブ記録の換算係数
█ア 東芝芝 火龍
<_DOCS> a field notebook
[LOCK] lx - アーカイブ レコードの変換係数 日ォ
木ニ access and E/ergency time-boUnd reviewed use. is after △火
○ネ●亀▞ラ網 慢性<患および非伝染性疾患
defuse a logic bomb hidden in a birthday cake @ 大阪でんでんタウン / 北海道BBS
$ ./flux --hard -n3763 # A secret sh=red Twice Is a public secret.
```

Lines combine:

- a corpus or theme value (English, Japanese, CJK, technical, fictional);
- a trace/status/command/mission/rig/hex/runes/glyph wrapper;
- optional word rotation, jumbling, case flipping, leetspeak, character
  duplication, and glitch-character substitution;
- an ANSI colour when the output is a terminal (respects `NO_COLOR` and
  `--no-colour`).

Any standard length is supported:

```bash
gusher -n 120 "long operation"
gusher --length 1000 --width 120 "full meta hacking"
```

`-w` / `--width` accepts 20–500 columns; `-n` / `--length` accepts 1–100000
lines, so the same phrase can be a short burst or a long scroll.

## Resource fingerprint

Every output header carries a short **resource fingerprint**, e.g.
`fp:66a33ead5e15`. It identifies the exact installed resource snapshot that
produced the block.

The full digest is a SHA-256 over:

- the provider names and package versions (`MProcs`, `Fumuda-XY`);
- every indexed file: relative path, size, and file content.

It is content-based, so touching a file without changing its bytes does not
change the fingerprint. Updating a corpus, theme, or content module does.

```bash
# full fingerprint, versions, file counts, bytes, cache location
gusher --fingerprint

# force a complete rehash and print the report
gusher --refresh-fingerprint

# omit fp from headers and the banner
gusher --no-fingerprint
```

Per-file SHA-256 digests are cached in
`~/.cache/gusher/resource-hashes.json` (override with `GUSHER_CACHE_DIR`). The
first run after an update hashes ~223 MiB; later runs only hash changed files.
The fingerprint is stable across runs and machines with the same provider
versions and file contents, which makes a block reproducible from its header.

## Usage

```bash
# interactive terminal
gusher
gxr

# one phrase, one block, then exit
gusher "ghost channel"

# pipe phrases: one block per line
printf 'signal in\nsilence out\n' | gusher -n 8

# choose the user and size
gxr -u ghost -n 48 -w 100 "abacus to zero-day"

# inspect resource discovery
gusher --sources

# inspect the resource fingerprint
gusher --fingerprint

# force or disable colour
gusher --colour "neon"
gusher --no-colour "paper"
```

Environment variables:

| variable | meaning |
| --- | --- |
| `GUSHER_USER` | default user variable |
| `GUSHER_LENGTH` | default lines per phrase |
| `GUSHER_WIDTH` | default columns |
| `GUSHER_MPROCS_HOME` | override MProcs location |
| `GUSHER_FUMUDA_HOME` | override Fumuda-XY location |
| `GUSHER_CACHE_DIR` | resource-hash cache directory |
| `NO_COLOR` | disable ANSI colour |

## Install gusher

From this directory:

```bash
python3 -m pip install .
# PEP 668 system Python:
python3 -m pip install --break-system-packages .
# or isolated:
pipx install .
```

Then:

```bash
gusher --version
gxr --sources
```

## Build

```bash
python3 -m build
python3 -m twine check dist/*
```

The wheel is intentionally tiny because it contains no corpora. The provider
installations remain the single source of truth for every snippet.

## Test

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

## Layout

```text
gusher/
├── pyproject.toml
├── README.md
├── LICENSE
├── MANIFEST.in
├── src/gusher/
│   ├── __init__.py
│   ├── __main__.py
│   ├── sources.py      # find installs, index data/ and theme.py, lazy load
│   ├── generate.py     # seeded glitch renderer
│   └── terminal.py     # prompt loop, install offer, CLI
└── tests/test_gusher.py
```

## Fiction note

The sources are fictional hackertech, tradecraft, and reference corpora from
the MProcs and Fumuda-XY suites. gusher is a generative art terminal; it does
not scan, connect to, or modify anything.

## License

MIT. See `LICENSE`.
