316622a78f
557 files merged. Conflicts resolved: - CHANGELOG.md: took refactor/lazy-loading (session changelog) - versions.ncl: took refactor/lazy-loading (adds typedialog entries)
99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# Core Provisioning Scripts
|
|
|
|
Reusable Nushell scripts for querying system state, validation, and metadata extraction.
|
|
|
|
## Purpose
|
|
|
|
These scripts provide a clean interface for:
|
|
- **Querying** system resources (providers, servers, clusters, etc.)
|
|
- **Validating** system state (commands, configuration)
|
|
- **Extracting** metadata (help categories, schema info)
|
|
|
|
## Usage Contexts
|
|
|
|
1. **Bash wrapper** (`provisioning/core/cli/provisioning`)
|
|
2. **CLI commands** (via dispatcher and command handlers)
|
|
3. **Direct invocation** (for debugging, testing, CI/CD)
|
|
4. **Other scripts** (as utilities)
|
|
|
|
## Scripts
|
|
|
|
### Query Scripts (Read-only resource listing)
|
|
|
|
| Script | Purpose | Usage |
|
|
| ------ | ------- | ----- |
|
|
| `query-providers.nu` | List all available providers | `nu query-providers.nu` |
|
|
| `query-taskservs.nu` | List all available taskservs | `nu query-taskservs.nu` |
|
|
| `query-servers.nu` | List servers in active workspace | `nu query-servers.nu [infra_filter]` |
|
|
| `query-clusters.nu` | List clusters in active workspace | `nu query-clusters.nu` |
|
|
| `query-infra.nu` | List infrastructures in active workspace | `nu query-infra.nu` |
|
|
|
|
**Output**: Table format (columns: name, type, status, etc.)
|
|
|
|
### Validation Scripts
|
|
|
|
| Script | Purpose | Usage |
|
|
| ------ | ------- | ----- |
|
|
| `validate-command.nu` | Validate if command exists in registry | `nu validate-command.nu <command_name>` |
|
|
| `validate-config.nu` | Validate configuration structure | `nu validate-config.nu` |
|
|
|
|
**Output**:
|
|
- `validate-command.nu`: `FOUND|true/false` or `NOT_FOUND`
|
|
- `validate-config.nu`: Validation errors or success message
|
|
|
|
### Metadata Scripts
|
|
|
|
| Script | Purpose | Usage |
|
|
| ------ | ------- | ----- |
|
|
| `get-help-category.nu` | Get help category for command | `nu get-help-category.nu <schema_file> <command>` |
|
|
|
|
**Output**: Help category string or empty
|
|
|
|
## Design Principles
|
|
|
|
1. ✅ **Single responsibility**: Each script does ONE thing
|
|
2. ✅ **Reusable**: Can be called from any context
|
|
3. ✅ **Testable**: Can run standalone with `nu --ide-check`
|
|
4. ✅ **Self-contained**: Minimal dependencies (lib_minimal.nu when needed)
|
|
5. ✅ **Structured output**: Consistent format for bash consumption
|
|
|
|
## Naming Convention
|
|
|
|
- `query-*.nu`: Read-only resource listing
|
|
- `validate-*.nu`: System state validation
|
|
- `get-*.nu`: Metadata extraction
|
|
|
|
## Guidelines
|
|
|
|
- Use `do { } | complete` pattern for error handling
|
|
- All scripts should be executable (`chmod +x`)
|
|
- Use `#!/usr/bin/env nu` shebang
|
|
- Source `lib_minimal.nu` when workspace functions needed
|
|
- Return structured output (table, string, or status code)
|
|
- No side effects (read-only operations)
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Syntax validation
|
|
nu --ide-check 50 query-providers.nu
|
|
|
|
# Functional testing
|
|
nu query-providers.nu
|
|
nu validate-command.nu platform
|
|
nu get-help-category.nu "$PROVISIONING/core/nulib/commands-registry.ncl" guides
|
|
```
|
|
|
|
## Migration from init-wrapper
|
|
|
|
These scripts were previously in `provisioning/core/cli/init-wrapper/` with different names:
|
|
- `provider-list.nu` → `query-providers.nu`
|
|
- `taskserv-list.nu` → `query-taskservs.nu`
|
|
- `server-list.nu` → `query-servers.nu`
|
|
- `cluster-list.nu` → `query-clusters.nu`
|
|
- `infra-list.nu` → `query-infra.nu`
|
|
- `validate-command.nu` → (same name)
|
|
- `validate-config.nu` → (same name)
|
|
- `get-help-category.nu` → (same name)
|
|
|
|
The new location (`core/nulib/scripts/`) reflects their general-purpose nature beyond just bash wrapper initialization.
|