Metadata-Version: 2.4
Name: magmascript
Version: 4.4.0
Summary: Scripting toolkit with domain-first subcommands
Author: Jake McCoy
License-Expression: MIT
Project-URL: Homepage, https://magmacrunch.com/ware/magmascript/
Project-URL: Documentation, https://magmacrunch.com/ware/magmascript/
Keywords: mcp,scripting,cli,magmacrunch
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == "cli"
Requires-Dist: prompt_toolkit>=3.0; extra == "cli"
Requires-Dist: pygments>=2.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: magmascript[cli,dev]; extra == "all"
Dynamic: license-file

# magmascript

Scripting toolkit with domain-first subcommands for managing magmacrunch.com infrastructure.

## Install

Requires Python >= 3.11.

### pip (recommended)

```bash
pip install magmascript
```

### pipx (best for CLI-only usage)

```bash
pipx install magmascript
```

### Homebrew (macOS / Linux)

```bash
brew install magmacrunch-media/tap/magmascript
```

### Development

```bash
git clone https://github.com/magmacrunch-media/magmascript.git
cd magmascript
python3 -m venv .venv
.venv/bin/pip install -e ".[all]"
```

## Configure

```bash
# Auto-configure from MCP server
magmascript configure

# Or manually set environment variables
export MAGMA_API_KEY="your-mcp-key"
export GITHUB_TOKEN=$(gh auth token)
export MAGMACRUNCH_ROOT="/path/to/magmacrunch.com"
```

Or use `~/.config/magmascript/config.toml`:

```toml
[mcp]
url = "https://magmacrunch.duckdns.org/mcp"
api_key = "your-key"

[pi.pi1]
host = "your-pi-host"
user = "jake"

[windows.mc1]
host = "your-windows-host"
user = "magma"

[gh]
token = "ghp_..."
owner = "magmacrunch-media"
repo = "magmacrunch.com"

[project]
root = "/path/to/magmacrunch.com"
```

Machines are named, so a second Pi or PC is one more section, such as
`[pi.pi2]`. With several of a kind, mark one `default = true` or pick per
command with `--host pi2`. The older single sections, `[pi]`, `[mc1]` and
`[mac]`, still work. See [Configuration](wiki/Configuration.md).

## MagmaScript Language

Write `.mgs` scripts using a Python-inspired mini language with direct access to all domains.

### Quick Start

```bash
# Run a script (shorthand)
magmascript scripts/examples/hello.mgs

# Run with arguments
magmascript scripts/examples/top-scores.mgs tetris

# Or use the explicit run subcommand
magmascript run scripts/examples/hello.mgs

# Start interactive REPL
magmascript repl

# Format files, keeping comments; --check lists, --write rewrites
magmascript fmt --check scripts/examples/*.mgs
```

`fmt` changes layout and nothing else. It keeps every comment, the author's
blank lines and any statement spread over several lines inside brackets, and
it checks the result parses to the same program with the same comments
before writing; a file it cannot keep whole is reported and left alone.

### Syntax Overview

```magmascript
// Variables
name = "MagmaCrunch"
version = 2

// String interpolation
print(f"Hello, {name} v{version}!")

// Functions
double = fn(x) { x * 2 }
result = double(21)

// Arrow functions
triple = x -> x * 3

// Script arguments
args_list = args()
if len(args_list) > 0 {
    print(f"First arg: {args_list[0]}")
}

// Control flow
if x > 10 {
    print("big")
} else {
    print("small")
}

// Loops
for i in range(5) {
    print(i)
}

while x > 0 {
    x = x - 1
}

// Dict literals
scores = {"Pong": 12, "Tetris": 45}
print(scores["Tetris"])

// List comprehensions
numbers = [1, 2, 3, 4, 5]
evens = [x for x in numbers if x % 2 == 0]
doubled = [x * 2 for x in numbers]

// String methods
csv = "apple,banana,cherry"
fruits = csv.split(",")
upper = [f.upper() for f in fruits]
print("-".join(upper))

// Domain calls work directly
boards = mcp.scoreboards()
for board in boards {
    print(f"{board.game}: {board.entries} entries")
}
```

### Language Features

#### Import System

```magmascript
// Import a module (access as namespace)
intent "utils.mgs"
result = utils.greet("World")

// Import with alias
intent "utils.mgs" as u
result = u.greet("World")

// Import specific names
intent { greet, farewell } from "utils.mgs"
result = greet("World")
```

#### Error Handling

```magmascript
try {
    result = risky_operation()
} haunter (e) {
    print(f"Error: {e.message}")
}

// Throw custom errors
throw fire toad("something went wrong")
```

MagmaCrunch error vocabulary:
- `haunter`: syntax/parse errors
- `fire toad`: runtime errors
- `devastate`: undefined variable errors
- `contemplate`: type errors
- `spooked`: warnings (non-fatal, prints to stderr)

```magmascript
spooked("this is a warning")
```

#### File I/O

```magmascript
content = quarry("data.txt")           // read file
litho("output.txt", "hello world")    // write file
```

#### HTTP Requests

```magmascript
response = http.get("https://api.example.com/data")
print(response.status)
print(response.json)

http.post("https://api.example.com/data", body={"key": "value"})
```

#### Shell Commands

```magmascript
result = exec("ls -la")
print(result.stdout)
print(result.exit_code)
```

#### Classes

```magmascript
class Dog {
    fn init(name) {
        self.name = name
    }

    fn bark(self) {
        return self.name + " says woof!"
    }
}

rex = Dog("Rex")
print(rex.bark())  // "Rex says woof!"
```

#### Default Parameters

```magmascript
fn greet(name, greeting="hello") {
    return greeting + ", " + name + "!"
}

greet("Jake")           // "hello, Jake!"
greet("Jake", "hey")    // "hey, Jake!"
```

#### Multi-Assignment

```magmascript
a, b = 1, 2
x, y, z = 10, 20, 30
a, b = [1, 2]  // list unpacking
```

#### `in` / `not in` Operators

```magmascript
if "key" in {"name": "Jake"} { ... }
if 5 not in [1, 2, 3] { ... }
if "xyz" not in "hello" { ... }
```

#### List/String Slicing

```magmascript
[1, 2, 3, 4, 5][0:3]     // [1, 2, 3]
[1, 2, 3][::-1]           // [3, 2, 1]
[0, 1, 2, 3, 4][::2]     // [0, 2, 4]
"hello world"[0:5]        // "hello"
"abcdef"[::-1]            // "fedcba"
```

#### Regex

```magmascript
"123abc".match("\\d+")            // ["123"] (match at start)
"abc123def456".findall("\\d+")    // ["123", "456"]
```

### Built-in Functions

| Function | Description |
|----------|-------------|
| `print(...)` | Print to stdout |
| `echo(...)` | Print to stdout (alias for print) |
| `len(x)` | Length of string, list, or dict |
| `type(x)` | Type name as string |
| `range(n)`, `range(start, stop)`, `range(start, stop, step)` | Generate integer ranges |
| `str(x)`, `int(x)`, `float(x)` | Type conversions |
| `abs(x)`, `min(...)`, `max(...)`, `sum(...)` | Math utilities |
| `keys(d)`, `values(d)` | Dict operations |
| `args()` | Get script arguments from CLI |
| `quarry(path)` | Read file contents |
| `litho(path, content)` | Write content to file |
| `exec(command)` | Execute shell command, returns `{stdout, stderr, exit_code}` |

### String Methods

| Method | Description |
|--------|-------------|
| `s.split(sep)` | Split string by separator |
| `s.join(list)` | Join list with string separator |
| `s.upper()` | Convert to uppercase |
| `s.lower()` | Convert to lowercase |
| `s.contains(sub)` | Check if substring exists |
| `s.replace(old, new)` | Replace substring |
| `s.length()` | Get string length |
| `s.startswith(prefix)` | Check if starts with prefix |
| `s.endswith(suffix)` | Check if ends with suffix |
| `s.strip()` | Remove leading/trailing whitespace |
| `s.match(pattern)` | Match regex at start, return groups or none |
| `s.findall(pattern)` | Find all non-overlapping regex matches |

### Example Scripts

See `scripts/examples/` for working examples:

| Script | Description |
|--------|-------------|
| `hello.mgs` | Hello World and basic features |
| `fibonacci.mgs` | Recursive functions and loops |
| `top-scores.mgs` | Arcade leaderboards (all games or single game) |
| `album-isrcs.mgs` | Get ISRCs/ISWCs for every song on an album |
| `album-lookup.mgs` | Album research: MusicBrainz + ISRC/ISWC + rights |
| `artist-rights.mgs` | Full artist rights catalog |
| `pi-health.mgs` | Pi system health check |
| `pi-traffic-report.mgs` | Nginx traffic analysis |
| `deploy-and-verify.mgs` | Deploy to Pi with service verification |
| `full-backup.mgs` | MusicBrainz backup pipeline |
| `weekly-scores.mgs` | Weekly scores report in markdown |
| `maintenance.mgs` | Weekly maintenance pipeline |
| `real-domains.mgs` | Test real domain connections (MCP search, scoreboards, games) |
| `domain-example.mgs` | Domain object overview and usage patterns |
| `astheno-list.mgs` | A linked list built by hand in the arena |
| `astheno-packing.mgs` | The same struct fields, two orderings, two sizes |
| `astheno-faults.mgs` | Every memory fault, caught and named |

### The Asthenosphere: explicit memory

The layer beneath the lithosphere. A second tier where you manage memory
yourself: a real byte arena, pointers, structs with visible padding, and
integers that wrap like C's.

It is not faster than the dynamic tier: an `i32` add still costs a Python
dispatch. What it gives you instead is the thing C cannot: the interpreter sees
every memory operation, so it catches the use-after-free, names the line that
leaked, and hex-dumps a struct with its fields labelled. **C's behavior, but
narrated.**

```magmascript
floorplan Point {
    tag: u8
    x: i32
    y: i32
}

layout(Point)              // prints the field table, padding rows included

p = garrison(Point)        // claim ground
p.x = i32(10)
p.y = i32(-20)
bathysphere(p)             // annotated hex dump
scorch(p)                  // release it
```

Widths are `i8 i16 i32 i64  u8 u16 u32 u64  f32 f64`. There is no integer
promotion, `i32 + u8` is an error pointing you at `osmosis()`, and `/`
truncates toward zero on integer widths, as C does.

Mistakes are reported, not swallowed:

```
quicksand at demo.mgs:line 4, column 7
    |
  4 | x = p.peek(i32)
    |       ^
this ground was scorched at line 3 (garrisoned at line 1)
```

| Fault | Reported as |
|--------|-------------|
| touching scorched ground | `quicksand`, naming the line that scorched it |
| reading outside a block | `area does not exist`, with the block's extent |
| never scorching | `spooked: ancient weeds` at exit, naming each garrison line |
| arithmetic that does not fit | `spooked`, with the exact value and the wrap |

`floorplan` is the only new reserved word; everything else is a shadowable
builtin, so existing scripts are unaffected. Full reference on the
[Asthenosphere wiki page](wiki/Asthenosphere.md).

### REPL

Start an interactive MagmaScript session:

```bash
magmascript repl
```

**Features:**
- Syntax highlighting via Pygments
- Tab completion for keywords, builtins, domain methods, and user-defined variables
- Persistent history across sessions (`~/.magmascript_history`)
- Multiline editing with proper continuation prompts
- Dot-commands:

| Command | Description |
|---------|-------------|
| `.help` | Show available commands |
| `.exit` | Exit the REPL |
| `.clear` | Clear the screen |
| `.ast` | Show AST for last expression |
| `.magma` | System status dashboard |
| `.crunch <target>` | Run batch pipeline |
| `.texas <target>` | Full/heavy operation |
| `.toast <target>` | Burn/clear caches |

## Domains

### MCP Domain: MusicBrainz, scores, Discogs, write operations
```bash
magmascript mcp scoreboards                  # game leaderboards
magmascript mcp scores tetris                # tetris scores
magmascript mcp search "radiohead"           # search MusicBrainz
magmascript mcp entities                     # all cached entities
magmascript mcp games                        # arcade games
magmascript mcp mb-search "album name"       # search MusicBrainz releases
magmascript mcp mb-release <mbid>            # get release details
magmascript mcp mb-recording <mbid>          # get recording details
```

### Pi Domain: Direct SSH to Raspberry Pi
```bash
magmascript pi status                        # all service statuses
magmascript pi logs arcade-chat              # service logs
magmascript pi restart arcade-chat           # restart service
magmascript pi info                          # uptime, memory, temp, disk
magmascript pi deploy arcade/chat-server.py  # deploy files
magmascript pi backup musicbrainz            # backup + commit to GitHub
magmascript pi traffic                       # nginx traffic analysis
```

### Windows PC domain (`windows`): management over SSH

Manages Windows PCs over SSH with PowerShell, any running OpenSSH. Each is
named in config as `[windows.<name>]`; `magmascript windows hosts` lists them,
and `--host <name>` picks one when there are several.

```magmascript
// In a .mgs script
info = windows.info()
print(f"CPU: {info.cpu_load}, Memory: {info.memory}")

other = windows.on("mc2").info()    // another configured PC

services = windows.services()
for svc in services {
    print(f"{svc.name}: {svc.status}")
}

windows.restart("OllamaSvc")
windows.set_power_mode("always-on")
```

Also on the CLI: `magmascript windows status`, `info`, `processes`,
`memory` (commit headroom, and WSL's real use apart from page cache),
`restart <service>`, `power`, `set-power-mode <always-on|sleep>`,
`wake <mac>`, `reboot`, each taking `--host <name>`.

`mc1`, the domain's old name, still works on the command line, in scripts and
as `MC1Client`: it means the host named `mc1`, or the default if none is.

> **Note:** `windows` commands connect over SSH, so run them from another
> machine. Run on the Windows PC they point at, they SSH into that same
> machine and hang.

### Mac Domain: Mac management (via SSH)
```magmascript
// In a .mgs script, or: magmascript mac info
info = mac.info()
print(f"{info.hostname}, {info.os_version}")
print(f"{info.cpu_name} ({info.cpu_cores} cores), {info.memory}")

// Keep a checkout in sync
print(mac.git_status())
mac.git_pull()
```

Also on the CLI: `magmascript mac info`, `mac processes`, `mac git-status`,
`mac git-pull`, `mac run "<cmd>"`.

### GitHub Domain: Direct API access
```bash
magmascript gh workflows                     # all workflow statuses
magmascript gh trigger "Deploy to Pi"        # trigger workflow
magmascript gh runners                       # self-hosted runners: online, busy
magmascript gh issues                        # list issues
magmascript gh file path/to/file.txt         # read file
magmascript gh sync                          # diff + commit all data files
```

### Scores Domain: Game high scores
```bash
magmascript scores list                      # all game leaderboards
magmascript scores get tetris                # tetris scores
magmascript scores report                    # markdown report
magmascript scores report --discord          # Discord JSON payload
magmascript scores reset tetris              # reset one game (backup created)
```

### Archive Domain: Archive page operations
```bash
magmascript archive check-format             # validate HTML formatting
magmascript archive generate-stubs           # generate stub HTML for new entities
```

### MusicBrainz Domain: MusicBrainz API client
```bash
magmascript mb backup                        # full MusicBrainz backup
magmascript mb backup --dry-run              # preview backup
magmascript mb backup --stale-only           # only refresh stale caches
```

### Last.fm Domain: Last.fm API client
```bash
magmascript lastfm fetch                     # fetch play counts
magmascript lastfm fetch --skip-existing     # skip cached artists
```

### Search Domain: Site search index builder
```bash
magmascript search build-index               # build search-index.json
magmascript search preview 10                # preview first 10 entries
```

### Rights Domain: Music rights metadata (ISRC, ISWC, ASCAP)
```bash
magmascript rights search "Farewell"         # search by title, ISRC, ISWC, or ASCAP ID
magmascript rights catalog "C.P. Rutledge"   # full rights catalog for an artist
magmascript rights export                    # TSV export for ASCAP forms
```

### Media Domain: Multi-provider media search
```bash
magmascript media search "sunset"            # search all providers
magmascript media providers                  # list available providers
```

### Cache Domain: Cache management
```bash
magmascript cache stats                      # show cache statistics
magmascript cache clear                      # clear all cache
```

### Magma: System status dashboard
```bash
magmascript magma                            # version, domains, cache stats
```

### Crunch: Batch pipeline
```bash
magmascript crunch mb                        # MusicBrainz backup
magmascript crunch lastfm                    # Last.fm fetch
magmascript crunch search                    # Build search index
magmascript crunch archive                   # Archive pages
magmascript crunch scores                    # Scores update
magmascript crunch gh                        # GitHub sync
magmascript crunch all                       # Run all targets
```

### Texas: Full/heavy operation (same targets, no shortcuts)
```bash
magmascript texas mb                         # Full MusicBrainz backup
magmascript texas lastfm                     # Full Last.fm fetch
magmascript texas search                     # Full search index rebuild
magmascript texas archive                    # Full archive processing
magmascript texas scores                     # Full scores update
magmascript texas gh                         # Full GitHub sync
magmascript texas all                        # Full heavy run
```

### Toast: Burn/clear caches
```bash
magmascript toast cache                      # Clear general cache
magmascript toast mb-cache                   # Clear MusicBrainz cache
magmascript toast lastfm-cache               # Clear Last.fm cache
magmascript toast scores-cache               # Clear scores cache
magmascript toast gh-cache                   # Clear GitHub cache
magmascript toast search-index               # Remove search index
magmascript toast all                        # Clear everything
```

### Domains from other packages

A package can publish its own domain by declaring an entry point; it then
appears in `.mgs` scripts and the REPL without any change to magmascript.

```toml
# in the other package's pyproject.toml
[project.entry-points."magmascript.domains"]
texastoast = "texastoast.mgs:TexastoastDomain"
```

The value names a class taking a single `config` argument. It is constructed on
first use, not at startup, so a domain may hold real resources. Built-in domains
win a name clash, and an entry point that fails to import is skipped rather than
breaking the interpreter.

[texastoast](https://github.com/magmacrunch-media/texastoast) is the first:
`pip install texastoast` and `.mgs` scripts can drive a game engine. It
registers under two names, `texastoast` and the shorter `tt`.

```magmascript
g = tt.game({"title": "hello", "width": 400, "height": 300})
```

A package may register the same class under several names this way; nothing
stops it, and the clients stay independent. Note that none of this touches the
`magmascript toast` CLI verb, which still clears caches, registry domains are
not dispatched as subcommands.

## Python Library

```python
from magmascript import MCPClient, PIClient, GHClient, RightsClient

# MCP
with MCPClient() as mcp:
    boards = mcp.scoreboards()
    releases = mcp.mb_search_releases("album name")

# Pi (direct SSH)
with PIClient() as pi:
    status = pi.services()
    info = pi.info()

# GitHub (direct API)
with GHClient() as gh:
    workflows = gh.workflows()

# Music rights metadata
with RightsClient() as rights:
    catalog = rights.catalog("C.P. Rutledge")
```

## Shell Helpers

```bash
source lib/magmascript.sh

mcp_scoreboards          # MCP commands
pi_status                # Pi commands
gh_workflows             # GitHub commands
```

## Documentation

Full documentation on the [Wiki](wiki/):
- [MagmaScript Language](wiki/MagmaScript-Language.md)
- [Configuration](wiki/Configuration.md)
- [MCP Domain](wiki/MCP-Domain.md)
- [Pi Domain](wiki/Pi-Domain.md)
- [Windows PC domain (`windows`)](wiki/Windows-Domain.md)
- [Mac Domain](wiki/Mac-Domain.md)
- [GitHub Domain](wiki/GitHub-Domain.md)
- [Scores Domain](wiki/Scores-Domain.md)
- [Rights Domain](wiki/Rights-Domain.md)
- [Archive Domain](wiki/Archive-Domain.md)
- [Last.fm Domain](wiki/Last.fm-Domain.md)
- [MusicBrainz Domain](wiki/MusicBrainz-Domain.md)
- [Search Domain](wiki/Search-Domain.md)
- [Media Domain](wiki/Media-Domain.md)
- [Example Scripts](wiki/Example-Scripts.md)
- [Asthenosphere](wiki/Asthenosphere.md)
- [Architecture](wiki/Architecture.md)

## Support This Project

If you find magmascript useful, consider supporting its development:

[![Sponsor](https://img.shields.io/badge/%E2%9D%A4_Sponsor-pink)](https://github.com/sponsors/magmacrunch-media)
[![PayPal](https://img.shields.io/badge/Donate-PayPal-blue)](https://www.paypal.biz/magmacrunchmedia)

## License

MIT
