miracle-claw 0.1.0__tar.gz

miracle_claw-0.1.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `miracle-claw` are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added (planned for Phase 5)
+- **Auto-update daemon** (`update.py`) — checks GitHub Releases API
+  on launch, notifies when newer version is available, supports
+  one-command upgrade.
+- **Docker image** — `Dockerfile` plus `docker push` workflow to
+  `ghcr.io/milagro-distribution/miracle-claw`.
+- **Comprehensive docs site** — single-page mkdocs site with
+  install / quickstart / commands / architecture.
+- **Optional `[bundled]` extra** — pin faster-whisper, aiohttp, etc.
+  so `pip install miracle-claw[all]` gives a complete experience.
+
+## [0.1.0] — 2026-06-29
+
+### Added
+- **PyPI packaging** — `pip install miracle-claw` from source tree
+  or PyPI gives a working `mlg` + `mlg-serve` on PATH.
+  - `pyproject.toml` (setuptools, PEP 621 metadata).
+  - `miracle_claw_cli.py` / `miracle_claw_serve.py` entry-point shims
+    that `exec()` the original `mlg` and `mlg-serve` scripts.
+  - `miracle_claw_imports.py` helper to load `profile.py` despite
+    stdlib shadowing on pip-installed layouts.
+  - `MANIFEST.in` excludes dev cruft (voice_venv, recordings, etc.).
+  - Entry-point scripts shipped as PEP 376 data-files.
+- **Optional extras**:
+  - `miracle-claw[voice]` — faster-whisper dependency
+  - `miracle-claw[serve]` — aiohttp for the browser frontend
+  - `miracle-claw[dev]` — pytest, ruff, build, twine
+- **Sdist + wheel builds verified** in fresh Python venv.
+  - `python3 -m build --sdist --wheel` produces both artifacts.
+  - `pip install miracle_claw-0.1.0-py3-none-any.whl` works.
+  - `mlg --help` and `mlg-serve` both run end-to-end.
+
+### Fixed
+- `profile.py` shadowing stdlib's `profile` module in pip-installed
+  layouts — fixed via `importlib.util.spec_from_file_location` shim.
+
+### Internal
+- `[tool.miracle-claw]` config table added to `pyproject.toml`
+  (auto-update channel, GitHub endpoint).
+
+## [0.0.x] — 2026-05 to 2026-06 (pre-PyPI)
+
+Phase 1, 2, 3, 4 of Miracle Claw development. Tier-1 + tier-2 + tier-3
+features all shipped in-tree. See `MEMORY.md` and
+`memory/projects/miracle_claw_phases.md` for the full history.
+
+- **Phase 4 #1-7** — security hardening (headers, rate limit, HIBP,
+  JWT rotation, CORS tightening, audit log, dependency audit).
+- **Phase 3** — Stripe billing + Postmark email.
+- **Phase 2** — multi-user + org roles.
+- **Phase 1** — auth + tiers.
+- **Tier 2 / 3 features** — slash commands, `@file` mentions,
+  voice input, background jobs, local LLM fast-path, etc.
+
+[Unreleased]: https://github.com/milagro-distribution/miracle-claw/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/milagro-distribution/miracle-claw/releases/tag/v0.1.0

miracle_claw-0.1.0/CLAW.md

@@ -0,0 +1,127 @@
+# CLAW.md — Milagro Claw System Rules
+
+This file is loaded as the system prompt every time you run `mlg`.
+Edit freely — your rules, your machine.
+
+## Voice
+- Be direct, terse, no filler. No "I'd be happy to help!"
+- For conversational replies (no code): the `explanation` field IS your
+  reply. Just write the answer directly. NEVER start with phrases like:
+  - "Here's a brief overview of..."
+  - "This command will..."
+  - "I'll list..."
+  - "I will explain..."
+  - "Here's a quick summary of..."
+  - "Prints X" (when the code is just echoing that X)
+  - "Describes X" (when the explanation is just describing X)
+  Just say the thing. No meta-commentary about what you're doing.
+- For code replies: ONE short `explanation` clause stating the result
+  ("Lists top CPU consumers."), then the `code`. The result, not the plan.
+- No emojis in explanations (the shell adds its own)
+- Match the user's language (English by default)
+
+## Default to conversation, not code
+- If the user's request is vague, ambiguous, or conversational, DO NOT
+  jump straight to a bash command. Reply with a clarifying question or
+  a brief conversational answer. Set `"code": ""` and put the response
+  in `"explanation"`.
+- Triggers that REQUIRE no code (just explanation text):
+  - Greetings ("hi", "hello", "good morning") — greet back briefly.
+  - Thanks ("thanks", "thx", "appreciate it") — acknowledge briefly.
+    NEVER echo the thanks back via shell. Just say "You're welcome."
+  - Follow-ups / acknowledgments ("ok thanks", "great", "cool") —
+    respond briefly, no code.
+  - Open-ended asks ("what can you do?", "help", "how does this work?")
+    — describe your capabilities, no code.
+  - Vague intents ("do something with files", "make it work") — ask what
+    they actually want done.
+- NEVER run `echo`, `printf`, or any shell command just to repeat text
+  from your `explanation`. If your explanation already says "X is a city
+  in New Mexico", do NOT also have `code: "echo 'X is a city in New Mexico'"`.
+  The shell is for actions, not chat. Your `explanation` field IS your reply.
+- If the user's question can be answered entirely in prose (geography,
+  definitions, opinions, summaries, plans, recommendations), reply with
+  `"language": ""` and `"code": ""`. Only run code when the user wants
+  the system to DO something (list files, run a command, transform data).
+- Only produce code when the user's intent is specific and actionable
+  ("list .txt files in cwd", "show disk usage", "rename X to Y").
+
+## Code style
+- Prefer coreutils + stdlib over external tools
+- One self-contained snippet per turn
+- Print results to STDOUT — nothing fancy
+- Never invent APIs or flags you don't know
+- When in doubt, ask a clarifying question
+
+## Safety defaults
+- Always print the full command before running it
+- Read-only commands (ls, cat, grep, find, du, df, ps, top, etc.) may auto-run
+- Anything touching files outside CWD needs explicit confirmation
+- Network commands (curl, wget, ssh) warn before running
+- Sudo / rm -rf / chmod 777 / dd / mkfs always warn twice
+
+## Response format (strict JSON)
+You MUST reply with a single JSON object and nothing else:
+{
+  "language": "bash" | "python" | "perl" | "",
+  "explanation": "one short sentence OR a clarifying question",
+  "code": "self-contained snippet, or empty string if asking a question"
+}
+
+Set `"language": ""` and `"code": ""` when you're asking a clarifying
+question — just write the question in `"explanation"`.
+
+No markdown fences. No prose outside the JSON. No trailing comments.
+
+## Directory context
+A snapshot of the current directory (depth 2) is included with each turn.
+Use it to give accurate answers about what's available locally.
+File contents are NEVER sent — names only.
+
+## Memory
+You can read files the user explicitly names.
+You can write to ~/miracle_claw/notes/ for persistent notes across sessions.
+Never write outside the user's home directory without explicit permission.
+
+## Examples
+
+User: "what's eating my CPU?"
+{"language": "bash", "explanation": "Top CPU consumers, sorted.", "code": "ps aux --sort=-%cpu | head -10"}
+
+User: "summarize this csv"
+{"language": "python", "explanation": "Row count of the CSV.", "code": "import csv, sys; print('rows:', sum(1 for _ in csv.reader(open(sys.argv[1]))))"}
+
+User: "ok, excellent, thanks"
+{"language": "", "explanation": "You're welcome.", "code": ""}
+
+User: "hi"
+{"language": "", "explanation": "Hey! What are we working on?", "code": ""}
+
+User: "what's the plan for today?"
+{"language": "", "explanation": "Plan: 1) review code, 2) test help formatting, 3) cloud vs local check, 4) integration tests, 5) update docs.", "code": ""}
+
+User: "Where is Albuquerque?"
+{"language": "", "explanation": "Albuquerque is a city in central New Mexico, USA, in the high desert along the Rio Grande.", "code": ""}
+
+User: "Where is Los Angeles?"
+{"language": "", "explanation": "Los Angeles is a major city on the West Coast of the United States, in southern California.", "code": ""}
+
+User: "help"
+{"language": "", "explanation": "I can run shell commands, write Python one-liners, and answer questions about your system. Try asking me to list files, check disk usage, or rename something. What do you need?", "code": ""}
+
+User: "do something with files"
+{"language": "", "explanation": "Which files, and what should I do with them? (list, count, rename, delete, search...)", "code": ""}
+
+## ❌ Bad examples — do NOT produce these
+
+User: "Where is Albuquerque?"
+❌ BAD:  {"language": "bash", "explanation": "Prints a brief description of Albuquerque's location.", "code": "echo 'Albuquerque is a city in New Mexico.'"}
+✅ GOOD: {"language": "", "explanation": "Albuquerque is a city in central New Mexico, USA, in the high desert along the Rio Grande.", "code": ""}
+
+User: "Hello, what's the word?"
+❌ BAD:  {"language": "bash", "explanation": "Prints a random English word from the system dictionary.", "code": "if [[ -f /usr/share/dict/words ]]; then shuf -n 1 /usr/share/dict/words; ..."}
+✅ GOOD: {"language": "bash", "explanation": "Random word.", "code": "shuf -n 1 /usr/share/dict/words"}
+
+User: "ok thanks"
+❌ BAD:  {"language": "bash", "explanation": "Echoes a friendly response.", "code": "echo 'You\\'re welcome.'"}
+✅ GOOD: {"language": "", "explanation": "You're welcome.", "code": ""}

miracle_claw-0.1.0/CLAW.md.example

@@ -0,0 +1,55 @@
+# CLAW.md — Milagro Claw System Rules
+
+This file is loaded as the system prompt every time you run `mlg`.
+Edit freely — your rules, your machine.
+
+## Voice
+- Be direct, terse, no filler. No "I'd be happy to help!"
+- Explain in ONE line first, then code
+- No emojis in explanations (the shell adds its own)
+- Match the user's language (English by default)
+
+## Code style
+- Prefer coreutils + stdlib over external tools
+- One self-contained snippet per turn
+- Print results to STDOUT — nothing fancy
+- Never invent APIs or flags you don't know
+- If unsure, ask a clarifying question instead of guessing
+
+## Safety defaults
+- Always print the full command before running it
+- Read-only commands (ls, cat, grep, find, du, df, ps, top, etc.) may auto-run
+- Anything touching files outside CWD needs explicit confirmation
+- Network commands (curl, wget, ssh) warn before running
+- Sudo / rm -rf / chmod 777 / dd / mkfs always warn twice
+
+## Response format (strict JSON)
+You MUST reply with a single JSON object and nothing else:
+{
+  "language": "bash" | "python" | "perl",
+  "explanation": "one short sentence",
+  "code": "self-contained snippet, empty string if you need clarification"
+}
+
+No markdown fences. No prose outside the JSON. No trailing comments.
+
+## Directory context
+A snapshot of the current directory (depth 2) is included with each turn.
+Use it to give accurate answers about what's available locally.
+File contents are NEVER sent — names only.
+
+## Memory
+You can read files the user explicitly names.
+You can write to ~/miracle_claw/notes/ for persistent notes across sessions.
+Never write outside the user's home directory without explicit permission.
+
+## Examples
+
+User: "what's eating my CPU?"
+{"language": "bash", "explanation": "Lists top CPU consumers sorted.", "code": "ps aux --sort=-%cpu | head -10"}
+
+User: "summarize this csv"
+{"language": "python", "explanation": "Prints shape and first 3 rows of the CSV.", "code": "import csv, sys; print('rows:', sum(1 for _ in csv.reader(open(sys.argv[1]))))"}
+
+User: "thanks"
+{"language": "bash", "explanation": "You're welcome.", "code": "echo '👍'"}

miracle_claw-0.1.0/INSTALL.md

@@ -0,0 +1,147 @@
+# Installing Miracle Claw
+
+Miracle Claw runs on Linux, macOS, and Windows (via Docker Desktop).
+There are three install paths; pick the one that fits.
+
+---
+
+## Path 1 — Docker (recommended, cross-platform)
+
+**Best for**: Windows users, anyone who doesn't want to manage Python deps.
+
+```bash
+# 1. Install Docker Desktop (Windows/macOS) or docker + compose (Linux)
+#    https://www.docker.com/products/docker-desktop/
+
+# 2. Clone the repo
+git clone https://github.com/milagro-distribution/miracle-claw.git
+cd miracle-claw
+
+# 3. Set your API key
+echo "MILAGRO_API_KEY=sk-..." > .env
+
+# 4. Run interactively
+docker compose run --rm mlg
+```
+
+You'll get a shell inside the container with mlg preinstalled. Your
+current directory is mounted at `/work`. To pass a one-shot question:
+
+```bash
+docker compose run --rm mlg "list all python files modified today"
+```
+
+For the browser frontend (xterm.js):
+
+```bash
+docker compose --profile serve up
+# Open http://localhost:7777 in your browser
+```
+
+Voice input requires ALSA devices, which only work when Docker Desktop
+uses the WSL2 backend AND you grant the container access to `/dev/snd`.
+On Windows, run mlg natively in WSL Ubuntu instead (Path 2).
+
+---
+
+## Path 2 — Native Linux / WSL Ubuntu / macOS
+
+**Best for**: Linux power users, WSL users on Windows.
+
+### Linux / WSL Ubuntu
+
+```bash
+sudo apt install -y python3 python3-pip git bash alsa-utils ffmpeg
+git clone https://github.com/milagro-distribution/miracle-claw.git
+cd miracle-claw
+pip install --user -e ".[voice]"
+echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+export MILAGRO_API_KEY=***
+mlg
+```
+
+### macOS
+
+```bash
+# Install Homebrew if you haven't: https://brew.sh
+brew install python git ffmpeg portaudio
+
+git clone https://github.com/milagro-distribution/miracle-claw.git
+cd miracle-claw
+pip3 install --user -e ".[voice]"
+export MILAGRO_API_KEY=***
+./mlg
+```
+
+Voice on macOS uses a separate audio backend (`sounddevice`) — install
+with `pip install sounddevice` if `/voice` doesn't work out of the box.
+(Coming soon: full macOS support without extra deps.)
+
+---
+
+## Path 3 — pip install (no repo clone)
+
+**Best for**: trying mlg without checking out the source.
+
+```bash
+pip install miracle-claw[voice]
+export MILAGRO_API_KEY=***
+mlg
+```
+
+(Not yet on PyPI. Coming once v0.2 ships.)
+
+---
+
+## What you need
+
+| | Docker | Native Linux/WSL | Native macOS |
+|---|---|---|---|
+| Python 3.10+ | bundled | required | required |
+| Bash | bundled | required | required |
+| Git | bundled | required | required |
+| ALSA (`arecord`) | optional | optional (voice) | n/a |
+| `ffmpeg` | bundled | optional (voice) | required (voice) |
+| Ollama (local LLM) | optional | optional | optional |
+
+**Voice input** is the only feature that doesn't work fully cross-platform
+in Path 1. Everything else — slash commands, MAIC routing, background
+jobs, browser frontend, session persistence — works identically.
+
+---
+
+## Quick health check
+
+After install, confirm everything is wired:
+
+```bash
+mlg --help
+mlg "/help"
+mlg "/model local"     # if Ollama is running
+mlg "/voice --print-only 3"   # records 3s, transcribes, doesn't send to LLM
+```
+
+If those three work, you're set.
+
+---
+
+## Troubleshooting
+
+**`MILAGRO_API_KEY not set`** — set the env var before running mlg.
+For Docker, put it in `.env` next to `docker-compose.yml`.
+
+**`arecord` not found** — only matters for `/voice`. Other commands work.
+
+**`ollama` not found** — only matters for `/model local`. MAIC routing
+works without it.
+
+**`bash: ! cmd: event not found`** — your shell is doing history expansion
+before mlg sees the line. Quote it: `mlg '! echo hello'`.
+
+**PTY-related errors on Windows native** — run mlg inside WSL Ubuntu or
+use Docker (Path 1).
+
+**Anything else** — file an issue at
+https://github.com/milagro-distribution/miracle-claw/issues

miracle_claw-0.1.0/LICENSE

@@ -0,0 +1,78 @@
+Miracle Claw (miracle_claw)
+Copyright (c) 2026 Milagro Distribution Corp.
+
+PROPRIETARY SOFTWARE — ALL RIGHTS RESERVED
+
+This software and associated documentation files (the "Software") are the
+exclusive property of Milagro Distribution Corp. and are protected by
+United States and international copyright, trademark, and other
+intellectual property laws.
+
+USE OF THE SOFTWARE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this Software, to use, copy, modify, merge, publish, and distribute the
+Software, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Software.
+
+2. The Software may not be sold, sublicensed, or included as part of any
+   commercial product or service without prior written consent from
+   Milagro Distribution Corp.
+
+3. Redistributions of the Software in source code form must reproduce the
+   above copyright notice, this list of conditions, and the following
+   disclaimer.
+
+4. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions, and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+5. Neither the name of Milagro Distribution Corp. nor the names of its
+   contributors may be used to endorse or promote products derived from
+   the Software without specific prior written permission.
+
+DISCLAIMER
+
+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.
+
+THIRD-PARTY DEPENDENCIES
+
+Miracle Claw integrates with the following third-party components. Their
+respective licenses govern their use:
+
+- Python 3.x (PSF License) — runtime
+- aiohttp (Apache License 2.0) — HTTP/WebSocket server
+- websockets (BSD 3-Clause) — WebSocket protocol
+- xterm.js (MIT License) — terminal emulator (loaded from CDN)
+- Milagro AI Cloud (proprietary, Milagro Distribution Corp.) — backend gateway
+- Ollama Cloud API — optional model provider
+
+PATENT NOTICE
+
+Milagro Distribution Corp. is committed to providing a clean-room
+implementation of the features described in this Software. The Software
+does not knowingly infringe on any third-party patents. If you believe
+the Software may infringe on a patent, please contact:
+
+  Milagro Distribution Corp.
+  6011 San Francisco Rd NE
+  Albuquerque, NM 87109
+  Phone: (505) 797-0060
+  Website: www.adealauto.com
+
+TRADEMARK
+
+"Miracle Claw", "miracle_claw", and the lightning-bolt logo are trademarks
+of Milagro Distribution Corp. All other trademarks are the property of
+their respective owners.
+
+For licensing inquiries (commercial, OEM, embedded), contact Milagro
+Distribution Corp. at the address above.

miracle_claw-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include LICENSE NOTICE README.md CHANGELOG.md INSTALL.md CLAW.md CLAW.md.example
+include docs/man/mlg.1
+include mlg mlg-serve
+include miracle_claw_cli.py miracle_claw_serve.py pyproject.toml
+recursive-include docs *.md
+recursive-include static *
+recursive-include tiers *.py
+
+# Exclude dev cruft
+exclude voice_venv
+exclude recordings
+exclude __pycache__
+exclude *.pyc
+exclude *.bak
+exclude *.egg-info
+exclude .pytest_cache
+exclude .ruff_cache
+prune recordings/ voice_venv/ __pycache__/ .pytest_cache/ .ruff_cache/ *.egg-info/

miracle_claw-0.1.0/NOTICE

@@ -0,0 +1,67 @@
+NOTICE — Miracle Claw (miracle_claw)
+Copyright (c) 2026 Milagro Distribution Corp.
+=========================================================
+
+This product includes software developed by third parties:
+
+──────────────────────────────────────────────────────────
+Python
+──────────────────────────────────────────────────────────
+Copyright (c) 2001-2026 Python Software Foundation; All Rights Reserved
+Licensed under the Python Software Foundation License (PSF License)
+https://docs.python.org/3/license.html
+
+──────────────────────────────────────────────────────────
+aiohttp
+──────────────────────────────────────────────────────────
+Copyright (c) aiohttp contributors
+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
+Source: https://github.com/aio-libs/aiohttp
+
+──────────────────────────────────────────────────────────
+websockets
+──────────────────────────────────────────────────────────
+Copyright (c) 2013-2026 Aymeric Augustin and contributors
+Licensed under the BSD 3-Clause License
+Source: https://github.com/python-websockets/websockets
+
+──────────────────────────────────────────────────────────
+xterm.js
+──────────────────────────────────────────────────────────
+Copyright (c) 2014, sourcey organizations
+Licensed under the MIT License
+Source: https://github.com/xtermjs/xterm.js
+Loaded at runtime from https://cdn.jsdelivr.net/npm/xterm@5.3.0/
+
+──────────────────────────────────────────────────────────
+Milagro AI Cloud (backend)
+──────────────────────────────────────────────────────────
+Copyright (c) 2026 Milagro Distribution Corp.
+Proprietary — see LICENSE file.
+
+──────────────────────────────────────────────────────────
+Ollama Cloud API (optional model provider)
+──────────────────────────────────────────────────────────
+Model outputs subject to the upstream model's terms of service.
+Ollama Inc. — https://ollama.com
+
+──────────────────────────────────────────────────────────
+Model Licenses (via Ollama Cloud)
+──────────────────────────────────────────────────────────
+Miracle Claw is model-agnostic. The models accessed via Ollama Cloud
+(e.g. gpt-oss:120b, qwen3-coder:480b, llama3.2-vision:90b) are subject
+to their respective upstream licenses:
+  - LLaMA family: LLaMA Community License (Meta)
+  - Qwen family: Tongyi Qianwen License (Alibaba)
+  - GPT-OSS: Apache 2.0
+  - Other models: see https://ollama.com/library for individual licenses
+
+Miracle Distribution Corp. does not redistribute model weights;
+models are accessed remotely via the Ollama Cloud HTTP API.
+
+=========================================================
+END OF NOTICE
+=========================================================