prvng_core/nulib/scripts/README.md

# 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.