Metadata-Version: 2.3
Name: kidshell
Version: 0.1.0a0
Summary: A REPL shell that is resilient in the face of childish expectations
Keywords: repl,shell,education,children,interactive,learning
Author: Anthony Wu
Author-email: Anthony Wu <ls-file-gh-issue@users.noreply.github.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: platformdirs>=4.3.6
Requires-Dist: requests>=2.27.1,<3.0
Requires-Dist: rich==14.1.0
Requires-Dist: scipy>=1.9,<2.0
Requires-Dist: sympy>=1.11,<2.0
Requires-Dist: textualize>=0.1,<1.0
Requires-Dist: tqdm>4.60,<5.0
Requires-Dist: typing-extensions>=3.7.4,<5.0 ; python_full_version < '3.10'
Requires-Python: >=3.9
Project-URL: Changelog, https://github.com/anthonywu/kidshell/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/anthonywu/kidshell/issues
Project-URL: Repository, https://github.com/anthonywu/kidshell
Description-Content-Type: text/markdown

# kidshell

![icon](./docs/icon-128.png)

A [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) shell that is resilient in the face of _childish expectations_.

> 🔒 **Security First**: kidshell implements comprehensive security measures to protect young users.

See [SECURITY.md](SECURITY.md) for details on our security features and vulnerability reporting.

## Quick Start

```bash
# Run without installation (recommended)
uvx kidshell
```

Once launched, think *"What would a child do?"* and try:

- **Colors**: `blue`, `red`, `green` (or any color name)
- **Emojis**: `bread`, `cat`, `star` (anything with an emoji)
- **Ranges**: `0...100...1` or `0...10000...10...0.01`
- **Math**: `1+1`, `pi`, `c`, `g`, `h`, `tau` (constants and expressions)
- **Symbolic algebra**:
  - `x`, `x + 3`, `x = 2`, then `x + 3` again
  - Define multiple variables: `x + y - z`
- **Just press Enter** - see what happens!
- **Smash the keyboard** - it handles gibberish gracefully

## Installation Options

### For Parents and IT Admin

```bash
# Fastest - no installation needed
uvx kidshell

# Traditional pip install
pip install kidshell

# Or any of these valid ways of installing kidshell as a reusable command
pipx install kidshell  # global in PATH
uv tool install kidshell  # global in PATH

# or into your preferred venv
python -m venv OR uv venv
source .venv/bin/activate
uv pip install kidshell  # into an isolated venv
```

### For Developers

See [DEVELOPMENT.md](DEVELOPMENT.md) for the complete development guide.

**Quick start:**
```bash
git clone https://github.com/anthonywu/kidshell.git
cd kidshell
just setup                      # Creates venv, installs deps
source .venv/bin/activate
just run                        # Run kidshell
```

## Custom Data Configuration

kidshell supports custom input→output mappings stored in platform-specific directories:

```bash
# Edit custom data
kidshell config                 # Opens editor with example.json
kidshell config edit mydata.json # Create/edit specific file
kidshell config list            # List all data files
kidshell config info            # Show config locations
```

Data files are JSON with custom mappings:

```json
{
  "hello": "👋",
  "world": "🌍",
  "cat": "🐱",
  "dog": "🐕"
}
```

## Project Structure

```
kidshell/
├── src/kidshell/       # Source code
│   ├── cli/           # CLI and REPL
│   ├── core/          # Core services
│   └── frontends/     # UI frontends
├── tests/             # Test files
├── justfile          # Development commands
└── pyproject.toml    # Project configuration
```

## Roadmap

1. 👥 Multiple profiles for N users in your family/classroom
1. 🖥 Run in browser or host at a web site
1. 📥 Load user/family configs from public https URLs
1. 📖 Dictionary database/API integration for spelling validation
1. 💬 Translation lookups for multilingual households
1. 🔊 Text-to-speech integration via [localtalk](https://github.com/anthonywu/localtalk)
1. ✨ Local/offline AI magic, if applicable and reasonably to introduce to children.
1. 🏞 Local/offline image generation with content moderation
1. 🧮 Expand usage of math libraries
1. 🌐 More UI languages

## Security

kidshell takes security seriously, especially given our young user base. We implement:

- **Path traversal protection** preventing unauthorized file system access
- **Safe JSON processing** without code execution risks
- **Subprocess security** with command validation and safe defaults
- **Secure file operations** confined to user-specific directories

For detailed security information, vulnerability reporting, and best practices, see [SECURITY.md](SECURITY.md).

## License

MIT

## Contributing

Contributions welcome! Please:
1. Review [SECURITY.md](SECURITY.md) for security guidelines
2. See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and workflow
3. Run `just check` before submitting PRs
4. Follow secure coding practices for any changes
