feat: Add new tools and configurations for Castle platform
- Introduced `uv.lock` for dependency management with various packages including `pytest`, `colorama`, and `pluggy`. - Added `pyrightconfig.json` for Python type checking configuration. - Expanded `recommendations.md` with detailed scaling recommendations and project management strategies. - Created shared `ruff.toml` for consistent linting across projects. - Developed `Castle Tools` with various utilities including Android backup, browser automation, document conversion, and search tools. - Implemented `backup-collect` and `schedule` tools for system administration tasks. - Enhanced `search` functionality with indexing and querying capabilities using Tantivy. - Added comprehensive documentation for each tool, including usage examples and installation instructions.
This commit is contained in:
141
tools/README.md
Normal file
141
tools/README.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Castle Tools
|
||||
|
||||
CLI utilities managed by the castle platform. Each tool follows Unix philosophy:
|
||||
read from stdin or file arguments, write to stdout, compose via pipes.
|
||||
|
||||
## Installation
|
||||
|
||||
Each category is its own package, installed individually:
|
||||
|
||||
```bash
|
||||
castle sync # installs all category packages
|
||||
```
|
||||
|
||||
Or manually install a single category:
|
||||
|
||||
```bash
|
||||
uv tool install --editable tools/document/
|
||||
```
|
||||
|
||||
## Tools by Category
|
||||
|
||||
### android (`castle-android`)
|
||||
|
||||
| Tool | Description | Requires |
|
||||
|------|-------------|----------|
|
||||
| `android-backup` | Backup Android device using ADB | adb |
|
||||
|
||||
### browser (`castle-browser`)
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `browser` | Browse the web using natural language via browser-use |
|
||||
|
||||
### document (`castle-document`)
|
||||
|
||||
| Tool | Description | Requires |
|
||||
|------|-------------|----------|
|
||||
| `docx2md` | Convert Word .docx files to Markdown | pandoc |
|
||||
| `html2text` | Convert HTML content to plain text | |
|
||||
| `md2pdf` | Convert Markdown files to PDF | pandoc, texlive-latex-base |
|
||||
| `pdf2md` | Convert PDF files to Markdown | pandoc, poppler-utils |
|
||||
|
||||
### gpt (`castle-gpt`)
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `gpt` | OpenAI text generation utility |
|
||||
|
||||
### mdscraper (`castle-mdscraper`)
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `mdscraper` | Combine text files into a single markdown document |
|
||||
|
||||
### search (`castle-search`)
|
||||
|
||||
| Tool | Description | Requires |
|
||||
|------|-------------|----------|
|
||||
| `docx-extractor` | Extract content and metadata from Word .docx files | pandoc |
|
||||
| `pdf-extractor` | Extract content and metadata from PDF files | |
|
||||
| `search` | Manage self-contained searchable collections of files | |
|
||||
| `text-extractor` | Extract content and metadata from text files | |
|
||||
|
||||
### system (`castle-system`)
|
||||
|
||||
| Tool | Description | Requires |
|
||||
|------|-------------|----------|
|
||||
| `backup-collect` | Collect files from various sources into backup directory | rsync |
|
||||
| `schedule` | Manage systemd user timers and scheduled tasks | |
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
tools/
|
||||
├── <category>/
|
||||
│ ├── pyproject.toml # Per-category package
|
||||
│ └── src/<category>/
|
||||
│ ├── __init__.py
|
||||
│ ├── <tool>.py # Implementation
|
||||
│ └── <tool>.md # Documentation (YAML frontmatter + docs)
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Each tool has two files:
|
||||
|
||||
- **`<tool>.py`** -- the implementation, with a `main()` entry point
|
||||
- **`<tool>.md`** -- YAML frontmatter (command, description, version, category,
|
||||
system_dependencies) followed by usage documentation
|
||||
|
||||
## Adding a New Tool
|
||||
|
||||
```bash
|
||||
castle create my-tool --type tool --category document
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
1. Create `tools/<category>/src/<category>/my_tool.py` with an argparse `main()` function
|
||||
2. Create `tools/<category>/src/<category>/my_tool.md` with YAML frontmatter
|
||||
3. Add the entry point to `tools/<category>/pyproject.toml`:
|
||||
```toml
|
||||
my-tool = "<category>.my_tool:main"
|
||||
```
|
||||
4. Register in `castle.yaml`:
|
||||
```yaml
|
||||
my-tool:
|
||||
description: What it does
|
||||
tool:
|
||||
tool_type: python_standalone
|
||||
category: <category>
|
||||
source: tools/<category>/
|
||||
install:
|
||||
path: { alias: my-tool }
|
||||
```
|
||||
5. Run `castle sync` to install
|
||||
|
||||
## Tool Types
|
||||
|
||||
Castle manages three types of tools:
|
||||
|
||||
| Type | Description | Installation |
|
||||
|------|-------------|-------------|
|
||||
| `python_standalone` | Own pyproject.toml | Individual `uv tool install` per category |
|
||||
| `script` | Bash or binary | Symlinked to `~/.local/bin/` |
|
||||
|
||||
## Conventions
|
||||
|
||||
- Read from stdin or file argument, write to stdout
|
||||
- Error messages and status to stderr
|
||||
- Exit 0 on success, 1 on error
|
||||
- `--help` for usage, `--version` where applicable
|
||||
- Composable via Unix pipes: `pdf2md paper.pdf | gpt "summarize this"`
|
||||
|
||||
## Managing Tools
|
||||
|
||||
```bash
|
||||
castle tool list # All tools grouped by category
|
||||
castle tool info <name> # Tool details + documentation
|
||||
castle list --role tool # Tools in the component listing
|
||||
castle info <name> --json # Full manifest including tool metadata
|
||||
```
|
||||
Reference in New Issue
Block a user