docs: update README and CHANGELOG for nickel branch (2026-05-12)
This commit is contained in:
Jesús Pérez
parent
749cbcf8b6
commit
0d202708b9
GPG key ID:
9F243E355E0BC939
7 changed files with 183 additions and 73 deletions
|
|
@ -43,6 +43,35 @@ repos:
|
|||
# pass_filenames: false
|
||||
# stages: [pre-push]
|
||||
|
||||
# ============================================================================
|
||||
# Ontoref Hooks (ACTIVE)
|
||||
# ============================================================================
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: manifest-coverage
|
||||
name: Manifest capability completeness
|
||||
entry: bash -c 'ONTOREF_ROOT="$(pwd)" ONTOREF_PROJECT_ROOT="$(pwd)" nu --no-config-file -c "use ./reflection/modules/sync.nu *; sync manifest-check"'
|
||||
language: system
|
||||
files: (\.ontology/|reflection/modes/|reflection/forms/).*\.ncl$
|
||||
pass_filenames: false
|
||||
stages: [pre-commit]
|
||||
|
||||
- id: docs-links
|
||||
name: Rustdoc broken intra-doc links
|
||||
entry: bash -c 'RUSTDOCFLAGS="-D rustdoc::broken-intra-doc-links -D rustdoc::private-intra-doc-links" cargo doc --manifest-path platform/Cargo.toml --no-deps --workspace -q'
|
||||
language: system
|
||||
types: [rust]
|
||||
pass_filenames: false
|
||||
stages: [pre-commit]
|
||||
|
||||
- id: docs-drift
|
||||
name: Crate //! doc drift check
|
||||
entry: bash -c 'nu -c "use ./reflection/modules/sync.nu; sync diff --docs --fail-on-drift"'
|
||||
language: system
|
||||
types: [rust]
|
||||
pass_filenames: false
|
||||
stages: [pre-commit]
|
||||
|
||||
# ============================================================================
|
||||
# Nushell Hooks (ACTIVE)
|
||||
# ============================================================================
|
||||
|
|
|
|||
88
CHANGELOG.md
88
CHANGELOG.md
|
|
@ -1,8 +1,88 @@
|
|||
# Provisioning Repository - Changes
|
||||
|
||||
**Date**: 2026-01-08
|
||||
---
|
||||
|
||||
## 2026-05-12 — nickel branch consolidation
|
||||
|
||||
### ADR-025 Amendments: Eager function-body parse (2026-04-17)
|
||||
|
||||
**Decision**: Nushell parses `use` statements inside function bodies at module-load time. Subprocess boundary is the only true lazy-load mechanism.
|
||||
|
||||
**Constraints added/amended**:
|
||||
|
||||
- `bash-wrapper-has-no-runner-reference` — now permits `provisioning-cli.nu` as transitional fallback
|
||||
- `universal-fallback-is-transitional` — 22 unmapped commands are explicit migration debt; must be resolved before lazy-load architecture is considered complete
|
||||
- `every-registry-command-has-thin-handler` — made directional (progress metric, not gate)
|
||||
|
||||
**Rejected approach**: Single-entry `provisioning-cli.nu` for hot paths — measured at 3.1s vs 0.08–0.15s for thin handlers. All 15 dispatcher wrappers fire at module-load regardless of invoked command.
|
||||
|
||||
**Files**: `adrs/adr-025-unified-lazy-loading.ncl`
|
||||
|
||||
---
|
||||
|
||||
### Platform Services Documentation (2026-02-03)
|
||||
|
||||
**All 10 platform services documented** with endpoint catalogue and local setup guide.
|
||||
|
||||
**Services**:
|
||||
|
||||
| Service | Endpoints | Notes |
|
||||
| ------- | --------- | ----- |
|
||||
| vault | 8 | Transit encryption, dynamic secrets |
|
||||
| registry | 6 | OCI extension distribution |
|
||||
| control-center | 12 | RBAC, audit, compliance |
|
||||
| rag | 5 | Vector search, document ingestion |
|
||||
| ai-service | 7 | Model routing, DAG execution |
|
||||
| mcp-server | 4 | AI-powered config tools |
|
||||
| daemon | 3 | State sync, health aggregation |
|
||||
| orchestrator | 8 | Workflow execution, checkpoints |
|
||||
| detector | 4 | Anomaly detection, alerts |
|
||||
| ui | 3 | Web control center frontend |
|
||||
|
||||
**Added**:
|
||||
|
||||
- `docs/src/operations/platform-services-inventory.md` — 50+ endpoints
|
||||
- `docs/src/operations/local-services-setup.md` — build, config, troubleshooting
|
||||
- `scripts/start-local-binaries.nu` — dependency-ordered service startup automation
|
||||
|
||||
---
|
||||
|
||||
### TypeDialog Migration (2026-01-09)
|
||||
|
||||
**`forminquire` fully replaced** by TOML-driven `typedialog` with TTY wrappers.
|
||||
|
||||
**New form registry** (`.typedialog/`):
|
||||
|
||||
- `core/forms/auth-login.toml`
|
||||
- `core/forms/mfa-enroll.toml`
|
||||
- `core/forms/setup-wizard.toml`
|
||||
- `core/forms/infrastructure/server_delete_confirm.toml`
|
||||
- `core/forms/infrastructure/cluster_delete_confirm.toml`
|
||||
- `core/forms/infrastructure/taskserv_delete_confirm.toml`
|
||||
- `core/forms/infrastructure/generic_delete_confirm.toml`
|
||||
- `platform/forms/ai-service-form.toml` (with Nickel fragment composition)
|
||||
- `platform/forms/control-center-form.toml`
|
||||
- `platform/forms/extension-registry-form.toml`
|
||||
|
||||
**Documentation**: `.typedialog/README.md`, `platform/forms/README.md`, `platform/forms/fragments/README.md`
|
||||
|
||||
**Architecture doc**: `docs/src/architecture/config-loading-architecture.md`
|
||||
|
||||
---
|
||||
|
||||
### Nushell 0.110.0 Compatibility (2026-01-21)
|
||||
|
||||
- Fixed `try`/`catch` syntax across `.typedialog/platform/scripts/`, `bootstrap/install.nu`, example deploy scripts
|
||||
- Updated `external.nu`, `paths.nu`, `export-toml.nu` for Nu 0.110.0 API changes
|
||||
- Removed stale session reports from `.coder/`
|
||||
- Relocated `nickel-installation-guide.md` into `docs/src/setup/`
|
||||
|
||||
---
|
||||
|
||||
## 2026-01-08 — Nickel IaC migration complete
|
||||
|
||||
**Repository**: provisioning (standalone, nickel branch)
|
||||
**Changes**: Nickel IaC migration complete - Legacy KCL and config cleanup
|
||||
**Changes**: Nickel IaC migration complete — Legacy KCL and config cleanup
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -129,3 +209,7 @@ nickel eval --format json <your-config.ncl> | jq '.'
|
|||
**Status**: Nickel migration complete. System is production-ready.
|
||||
**Date**: 2026-01-08
|
||||
**Branch**: nickel
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-05-12*
|
||||
|
|
|
|||
75
README.md
75
README.md
|
|
@ -23,7 +23,7 @@
|
|||
|
||||
---
|
||||
|
||||
## What is Provisioning?
|
||||
## What is Provisioning
|
||||
|
||||
**Provisioning** is a comprehensive **Infrastructure as Code (IaC)** platform designed to manage
|
||||
complete infrastructure lifecycles: cloud providers, infrastructure services, clusters,
|
||||
|
|
@ -78,7 +78,7 @@ Declarative Infrastructure as Code (IaC) platform providing:
|
|||
|
||||
---
|
||||
|
||||
## Why Provisioning?
|
||||
## Why Provisioning
|
||||
|
||||
### The Problems It Solves
|
||||
|
||||
|
|
@ -509,7 +509,8 @@ Three native Rust plugins providing 10-50x performance improvements over HTTP AP
|
|||
|
||||
Enterprise-grade security with 39,699 lines across 12 components.
|
||||
|
||||
- **12 Components**: JWT Auth, Cedar Authorization, MFA (TOTP + WebAuthn), Secrets Management, KMS, Audit Logging, Break-Glass, Compliance, Audit Query, Token Management, Access Control, Encryption
|
||||
- **12 Components**: JWT Auth, Cedar Authorization, MFA (TOTP + WebAuthn), Secrets Management,
|
||||
KMS, Audit Logging, Break-Glass, Compliance, Audit Query, Token Management, Access Control, Encryption
|
||||
- **Performance**: <20ms overhead per secure operation
|
||||
- **Testing**: 350+ comprehensive test cases
|
||||
- **API**: 83+ REST endpoints, 111+ CLI commands
|
||||
|
|
@ -531,7 +532,7 @@ Enterprise-grade security with 39,699 lines across 12 components.
|
|||
|
||||
| Technology | Version | Purpose | Why |
|
||||
| ------------ | --------- | --------- | ----- |
|
||||
| **Nickel** | Latest | PRIMARY - Infrastructure-as-code language | Type-safe schemas, lazy evaluation, LSP support, composable records, gradual validation |
|
||||
| **Nickel** | Latest | PRIMARY - Infrastructure-as-code language | Type-safe schemas, lazy evaluation, LSP support, composable records |
|
||||
| **Nushell** | 0.109.0+ | Scripting and task automation | Structured data pipelines, cross-platform, modern built-in parsers (JSON/YAML/TOML) |
|
||||
| **Rust** | Latest | Platform services (orchestrator, control-center, installer) | Performance, memory safety, concurrency, reliability |
|
||||
| **KCL** | DEPRECATED | Legacy configuration (fully replaced by Nickel) | Migration bridge available; use Nickel for new work |
|
||||
|
|
@ -540,7 +541,7 @@ Enterprise-grade security with 39,699 lines across 12 components.
|
|||
|
||||
| Technology | Version | Purpose | Features |
|
||||
| ------------ | --------- | --------- | ---------- |
|
||||
| **SurrealDB** | Latest | High-performance graph database backend | Multi-model (document, graph, relational), real-time queries, distributed architecture, complex relationship tracking |
|
||||
| **SurrealDB** | Latest | High-performance graph database backend | Multi-model (document, graph, relational), real-time queries, distributed |
|
||||
|
||||
### Platform Services (Rust-based)
|
||||
|
||||
|
|
@ -1078,48 +1079,46 @@ See [LICENSE](LICENSE) file in project root.
|
|||
---
|
||||
|
||||
**Maintained By**: Architecture Team
|
||||
**Last Updated**: 2026-01-08 (Version Management System v3.6.0 + Nickel v5.0.0 Migration Complete)
|
||||
**Last Updated**: 2026-05-12
|
||||
**Current Branch**: nickel
|
||||
**Project Home**: [provisioning/](provisioning/)
|
||||
|
||||
---
|
||||
|
||||
## Recent Changes (2026-01-08)
|
||||
## Recent Changes (2026-05-12)
|
||||
|
||||
### Version Management System (v3.6.0)
|
||||
### ADR-025: Eager function-body parse + transitional fallback (2026-04-17)
|
||||
|
||||
**What Changed**:
|
||||
- ✅ Implemented `provisioning setup versions` command
|
||||
- ✅ Generates bash-compatible `/provisioning/core/versions` file
|
||||
- ✅ Automatically discovers and includes all provider versions from Nickel schemas
|
||||
- ✅ Fixed to remove redundant metadata (all sources are Nickel)
|
||||
- ✅ Core tools with aliases: NUSHELL→NU, NICKEL, SOPS, AGE, K9S
|
||||
- ✅ Shell script integration: `source /provisioning/core/versions && echo $NU_VERSION`
|
||||
**Architectural finding with lasting constraints**:
|
||||
|
||||
**Files Modified**:
|
||||
- `provisioning/core/nulib/lib_provisioning/setup/utils.nu` - Core implementation
|
||||
- `provisioning/core/nulib/main_provisioning/commands/setup.nu` - Command routing
|
||||
- `provisioning/core/nulib/lib_provisioning/workspace/enforcement.nu` - Workspace exemption
|
||||
- `provisioning/README.md` - Documentation updates
|
||||
- Nushell parses `use` statements inside function bodies at **module-load time**, not call time. Subprocess boundary is the only true lazy-load mechanism.
|
||||
- `provisioning-cli.nu` single-entry point tested and rejected for hot paths: 3.1s vs 0.08–0.15s
|
||||
with thin handlers. All 15 dispatcher wrappers fire at module-load regardless of which command runs.
|
||||
- 22 unmapped commands documented as migration debt (`universal-fallback-is-transitional` constraint).
|
||||
- `bash-wrapper-has-no-runner-reference` amended to permit `provisioning-cli.nu` fallback during migration.
|
||||
|
||||
**Generated File Example**:
|
||||
```bash
|
||||
NUSHELL_VERSION="0.109.1"
|
||||
NUSHELL_SOURCE="https://github.com/nushell/nushell/releases"
|
||||
NU_VERSION="0.109.1"
|
||||
NU_SOURCE="https://github.com/nushell/nushell/releases"
|
||||
### Platform Services Documentation (2026-02-03)
|
||||
|
||||
NICKEL_VERSION="1.15.1"
|
||||
NICKEL_SOURCE="https://github.com/tweag/nickel/releases"
|
||||
**All 10 platform services fully documented**:
|
||||
|
||||
PROVIDER_AWS_VERSION="2.32.11"
|
||||
PROVIDER_AWS_SOURCE="https://github.com/aws/aws-cli/releases"
|
||||
# ... and more providers
|
||||
```
|
||||
- Services: vault, registry, control-center, rag, ai, mcp, daemon, orchestrator, detector, ui
|
||||
- 50+ REST endpoints catalogued with method, path, auth requirements
|
||||
- `start-local-binaries.nu` — automation script with dependency resolution for local development
|
||||
- Local Services Setup Guide added to `docs/src/operations/`
|
||||
|
||||
**Key Improvements**:
|
||||
- Clean metadata (no redundant `_LIB` fields - all sources are Nickel)
|
||||
- Automatic provider discovery from `extensions/providers/*/nickel/version.ncl`
|
||||
- Direct Nickel file parsing with JSON export
|
||||
- Zero dependency on environment variables or legacy systems
|
||||
- 100% bash/shell compatible for deployment scripts
|
||||
### TypeDialog Migration (2026-01-09)
|
||||
|
||||
**`forminquire` fully replaced by `typedialog`**:
|
||||
|
||||
- All interactive forms migrated to TOML-driven `typedialog` schema
|
||||
- TTY wrapper scripts for terminal-safe form rendering
|
||||
- Core forms: `auth-login`, `mfa-enroll`, `setup-wizard`
|
||||
- Infrastructure delete confirmations: server, cluster, taskserv, generic
|
||||
- Platform forms: ai-service, control-center, extension-registry with Nickel fragment composition
|
||||
|
||||
### Nushell 0.110.0 Compatibility (2026-01-21)
|
||||
|
||||
- Fixed `try-catch` syntax across bootstrap, scripts, and typedialog Nu scripts
|
||||
- Reviewed and updated: `export-toml.nu`, `external.nu`, `paths.nu`, `configure.nu`
|
||||
- Removed obsolete `.coder/` session reports; documentation structure reorganized
|
||||
- Config loading architecture document added: `docs/src/architecture/config-loading-architecture.md`
|
||||
|
|
|
|||
|
|
@ -81,19 +81,19 @@ provisioning_binaries := "provisioning-ai-service provisioning-extension-registr
|
|||
# Install binaries locally (default: ~/.local/bin)
|
||||
distro-install:
|
||||
#!/usr/bin/env bash
|
||||
|
||||
|
||||
INSTALL_DIR="{{distro_install_dir}}"
|
||||
BUILD_DIR="{{distro_build_dir}}"
|
||||
PROVISIONING_ROOT="{{provisioning_root}}"
|
||||
|
||||
|
||||
echo "📦 Installing provisioning binaries to: $INSTALL_DIR"
|
||||
mkdir -p "$INSTALL_DIR" || { echo "✗ Failed to create install directory"; exit 1; }
|
||||
|
||||
|
||||
echo ""
|
||||
echo "📂 Installing binaries..."
|
||||
binaries_installed=0
|
||||
binaries_failed=0
|
||||
|
||||
|
||||
for binary in {{provisioning_binaries}}; do
|
||||
SRC="$BUILD_DIR/$binary"
|
||||
if [ -f "$SRC" ]; then
|
||||
|
|
@ -109,14 +109,14 @@ distro-install:
|
|||
((binaries_failed++))
|
||||
fi
|
||||
done
|
||||
|
||||
|
||||
echo ""
|
||||
echo "📊 Installation Summary"
|
||||
echo "====================="
|
||||
echo "Install directory: $INSTALL_DIR"
|
||||
echo "Binaries installed: $binaries_installed"
|
||||
[ $binaries_failed -gt 0 ] && echo "Binaries failed: $binaries_failed"
|
||||
|
||||
|
||||
# Check if install dir is in PATH
|
||||
if ! echo "$PATH" | grep -q "$INSTALL_DIR"; then
|
||||
echo ""
|
||||
|
|
@ -124,7 +124,7 @@ distro-install:
|
|||
echo "Add to ~/.bashrc or ~/.zshrc:"
|
||||
echo " export PATH=\"\$PATH:$INSTALL_DIR\""
|
||||
fi
|
||||
|
||||
|
||||
echo ""
|
||||
echo "✅ Installation complete!"
|
||||
echo ""
|
||||
|
|
@ -134,12 +134,12 @@ distro-install:
|
|||
# Install to system directory (requires sudo)
|
||||
distro-install-system:
|
||||
#!/usr/bin/env bash
|
||||
|
||||
|
||||
INSTALL_DIR="/usr/local/bin"
|
||||
BUILD_DIR="{{distro_build_dir}}"
|
||||
|
||||
|
||||
echo "🔐 Installing provisioning binaries to: $INSTALL_DIR (requires sudo)"
|
||||
|
||||
|
||||
for binary in {{provisioning_binaries}}; do
|
||||
SRC="$BUILD_DIR/$binary"
|
||||
if [ -f "$SRC" ]; then
|
||||
|
|
@ -153,25 +153,25 @@ distro-install-system:
|
|||
echo " ✗ $binary (not found)"
|
||||
fi
|
||||
done
|
||||
|
||||
|
||||
echo "✅ System installation complete!"
|
||||
|
||||
# Uninstall binaries
|
||||
distro-uninstall:
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
|
||||
|
||||
INSTALL_DIR="{{distro_install_dir}}"
|
||||
|
||||
|
||||
echo "🗑️ Uninstalling provisioning binaries from: $INSTALL_DIR"
|
||||
|
||||
|
||||
for binary in {{provisioning_binaries}}; do
|
||||
if [ -f "$INSTALL_DIR/$binary" ]; then
|
||||
rm "$INSTALL_DIR/$binary"
|
||||
echo " ✓ Removed $binary"
|
||||
fi
|
||||
done
|
||||
|
||||
|
||||
echo "✅ Uninstallation complete!"
|
||||
|
||||
# ============================================================================
|
||||
|
|
@ -181,15 +181,15 @@ distro-uninstall:
|
|||
# Verify installation integrity
|
||||
distro-verify:
|
||||
#!/usr/bin/env bash
|
||||
|
||||
|
||||
INSTALL_DIR="{{distro_install_dir}}"
|
||||
|
||||
|
||||
echo "🔍 Verifying installation in: $INSTALL_DIR"
|
||||
echo ""
|
||||
|
||||
|
||||
found=0
|
||||
missing=0
|
||||
|
||||
|
||||
for binary in {{provisioning_binaries}}; do
|
||||
if [ -f "$INSTALL_DIR/$binary" ] && [ -x "$INSTALL_DIR/$binary" ]; then
|
||||
echo " ✓ $binary"
|
||||
|
|
@ -199,26 +199,26 @@ distro-verify:
|
|||
((missing++))
|
||||
fi
|
||||
done
|
||||
|
||||
|
||||
echo ""
|
||||
echo "📊 Summary: $found found, $missing missing"
|
||||
|
||||
|
||||
if [ $missing -gt 0 ]; then
|
||||
echo "⚠️ Some binaries are missing!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
|
||||
echo "✅ Installation verified!"
|
||||
|
||||
# List installed binaries
|
||||
distro-list:
|
||||
#!/usr/bin/env bash
|
||||
|
||||
|
||||
INSTALL_DIR="{{distro_install_dir}}"
|
||||
|
||||
|
||||
echo "📋 Installed provisioning binaries in: $INSTALL_DIR"
|
||||
echo ""
|
||||
|
||||
|
||||
if ls "$INSTALL_DIR"/provisioning-* 2>/dev/null | head -1 > /dev/null; then
|
||||
ls -lh "$INSTALL_DIR"/provisioning-*
|
||||
else
|
||||
|
|
@ -270,17 +270,17 @@ distro-info:
|
|||
@distro-checksums:
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
|
||||
|
||||
PACKAGES_DIR="{{packages_dir}}"
|
||||
|
||||
|
||||
if [ ! -d "$PACKAGES_DIR" ]; then
|
||||
echo "✗ Packages directory not found: $PACKAGES_DIR"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
|
||||
echo "🔐 Generating SHA256 checksums..."
|
||||
cd "$PACKAGES_DIR"
|
||||
|
||||
|
||||
count=0
|
||||
for file in *.tar.gz *.zip 2>/dev/null; do
|
||||
[ -f "$file" ] || continue
|
||||
|
|
@ -288,7 +288,7 @@ distro-info:
|
|||
sha256sum "$file" > "${file}.sha256"
|
||||
((count++))
|
||||
done
|
||||
|
||||
|
||||
echo "✅ Generated $count checksums"
|
||||
|
||||
# ============================================================================
|
||||
|
|
|
|||
|
|
@ -83,4 +83,3 @@ let contract = std.contract in
|
|||
else 'Error {message = "rate_limit_requests must be between 10 and 10000"}
|
||||
),
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -125,4 +125,3 @@ let docker_build_schema = import "schemas/platform/docker-build.ncl" in
|
|||
build | docker_build_schema.DockerBuildConfig | optional,
|
||||
},
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ use std log
|
|||
# Uses PROVISIONING_USER_PLATFORM env var if set, otherwise defaults to OS-specific path
|
||||
def get-platform-base-dir [] {
|
||||
let env_path = ($env.PROVISIONING_USER_PLATFORM? | default "")
|
||||
|
||||
|
||||
if ($env_path | is-empty) {
|
||||
# Fallback to OS-specific default location
|
||||
let home = $nu.home-dir
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue