9cef9b8d57
Merge _configs/ into config/ for single configuration directory. Update all path references. Changes: - Move _configs/* to config/ - Update .gitignore for new patterns - No code references to _configs/ found Impact: -1 root directory (layout_conventions.md compliance)
285 lines
6.7 KiB
Markdown
285 lines
6.7 KiB
Markdown
# 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
|