syntaxis/scripts/README.md

# syntaxis Scripts

Infrastructure and utility scripts for syntaxis project management.

## Active Scripts

### 1. `common/find-config.nu`

**Purpose**: Configuration file discovery utility for syntaxis scripts and binaries.

**Search Order**:
1. `.syntaxis/{filename}` - syntaxis specific config
2. `.project/{filename}` - Generic project config
3. `.coder/{filename}` - Documentation/tracking config
4. `{filename}` - Current directory fallback

**Functions**:
```nushell
# Find config file (returns path or empty string)
let config = (find-config "workspace.toml")

# Find with default fallback
let config = (find-config-or "config.toml" "default.toml")

# Find database file
let db_path = (find-db-path "workspace.db")
```

**Usage**: Import in other scripts:
```nushell
use scripts/common/find-config.nu [find-config, find-config-or, find-db-path]
```

**Status**: ✅ Active | **Source**: Adapted from Tools/scripts/common/find-config.nu

---

### 2. `install-cli.nu`

**Purpose**: Auto-discovery and installation of syntaxis binaries.

**Features**:
- Auto-discovery of all binaries in workspace (CLI, TUI, Dashboard, API)
- Install all binaries with one command
- Optional target directory cleanup (saves disk space)
- Installation status tracking
- Binary listing

**Available Binaries**:
- `workspace` - Project management CLI
- `syntaxis-tui` - Interactive terminal interface
- `syntaxis-dashboard` - Web UI (Leptos)
- `syntaxis-api` - REST API server (work-in-progress)

**Usage**:
```bash
# Install all binaries
nu scripts/install-cli.nu all

# Install all (keep build artifacts)
nu scripts/install-cli.nu all --keep-target

# Install specific binary
nu scripts/install-cli.nu workspace

# Check installation status
nu scripts/install-cli.nu status

# List available binaries
nu scripts/install-cli.nu list

# Show help
nu scripts/install-cli.nu help
```

**Status**: ✅ Active | **Source**: Adapted from Tools/scripts/cli_install.nu

---

### 3. `manifest.nu`

**Purpose**: Track installed binaries and configurations in syntaxis.

**Features**:
- Load/save manifest from `.syntaxis/manifest.toml`
- Register/unregister binary installations
- Enable/disable binaries
- Track configuration state
- Show installation summary

**Functions**:
```nushell
# Load current manifest
let manifest = (load-manifest)

# Register a newly installed binary
register-binary "workspace" "0.1.0" "core/crates/syntaxis-cli"

# List all installed binaries
list-binaries

# Enable/disable binaries
enable-binary "workspace"
disable-binary "syntaxis-api"

# Show full manifest
show-manifest
```

**Manifest File**: `.syntaxis/manifest.toml`
- Tracks all installed binaries with timestamps
- Records enabled/disabled state
- Configuration tracking

**Status**: ✅ Active | **Source**: Adapted from Tools/scripts/manifest.nu

---

### 4. `manifest.toml.template`

**Purpose**: Template for installation manifest tracking.

**Location**: `.syntaxis/manifest.toml` (created by `install-cli.nu`)

**Tracks**:
- Binary installation timestamps
- Binary versions
- Configuration states
- Installation metadata

**Status**: ✅ Active | **Auto-generated by**: install-cli.nu and manifest.nu

---

## Quick Command Reference

| Command | Purpose |
|---------|---------|
| `nu scripts/install-cli.nu all` | Install all binaries |
| `nu scripts/install-cli.nu status` | Show installation status |
| `nu scripts/install-cli.nu list` | List available binaries |
| `nu scripts/manifest.nu show-manifest` | Show full manifest |
| `nu scripts/manifest.nu list-binaries` | List installed binaries |

---

## Installation Workflow

### First-time Setup

```bash
# 1. Install all binaries
nu scripts/install-cli.nu all

# 2. Verify installation
nu scripts/install-cli.nu status

# 3. Check manifest
nu scripts/manifest.nu show-manifest

# 4. Use workspace CLI
workspace --help
syntaxis-tui
```

### After Code Changes

```bash
# 1. Rebuild and reinstall
cargo build --release -p syntaxis-cli
cargo install --path core/crates/syntaxis-cli

# OR use install script to reinstall all:
nu scripts/install-cli.nu all --keep-target
```

### Manifest Management

```bash
# View what's installed
nu scripts/manifest.nu show-manifest

# Enable/disable specific binaries
nu scripts/manifest.nu enable-binary "workspace"
nu scripts/manifest.nu disable-binary "syntaxis-api"

# List configurations
nu scripts/manifest.nu list-configs
```

---

## Configuration Discovery

Scripts automatically find configuration files in this order:

1. **`.syntaxis/`** - syntaxis specific configs
2. **`.project/`** - Generic project configs
3. **`.coder/`** - Documentation tracking
4. **Current directory** - Fallback

**Example usage in scripts**:
```nushell
use scripts/common/find-config.nu [find-config]

# Find config with fallback
let config_path = (find-config-or "workspace.toml" ".syntaxis/workspace.toml")
let config = (open $config_path)
```

---

## Development Guidelines

### Adding New Scripts

1. **Use NuShell** (not Bash) - consistent with syntaxis standards
2. **Place in appropriate directory**:
   - `common/` - Shared utility functions
   - Root `scripts/` - Main executable scripts
3. **Include documentation** with USAGE and EXAMPLES
4. **Use `find-config`** for config discovery
5. **Test before committing**: `nu scripts/your-script.nu help`

### Example Script Template

```nushell
#!/usr/bin/env nu

# Description: What this script does
#
# USAGE:
#   nu scripts/my-script.nu [OPTIONS]
#
# EXAMPLES:
#   nu scripts/my-script.nu help       # Show help
#   nu scripts/my-script.nu status     # Check status

use scripts/common/find-config.nu [find-config]

def print_help [] {
    print "Usage documentation..."
}

def main [action?: string] {
    if ($action == null or $action == "help") {
        print_help
        return
    }
    # Implementation
}
```

---

## File Structure

```
core/scripts/
├── README.md                        # This file
├── manifest.toml.template           # Template for manifest tracking
├── install-cli.nu                   # Binary installer & discovery
├── manifest.nu                      # Manifest management utilities
└── common/
    └── find-config.nu              # Config file discovery
```

---

## Related Documentation

- [.claude/PROJECT_RULES.md](../.claude/PROJECT_RULES.md) - Architecture & standards
- [.claude/DEVELOPMENT.md](../.claude/DEVELOPMENT.md) - Development workflow
- [Justfile](../Justfile) - Build automation
- [MIGRATION_STATUS.md](../MIGRATION_STATUS.md) - Project migration tracking

---

## Notes

- All scripts use NuShell for consistency with syntaxis standards
- Scripts automatically discover configs using standard paths
- Manifest tracking enables reproducible binary installations
- See `.claude/` directory for development guidelines and standards