6a59d34bb1
Update configuration files, templates, and internal documentation for the provisioning repository system. Configuration Updates: - KMS configuration modernization - Plugin system settings - Service port mappings - Test cluster topologies - Installation configuration examples - VM configuration defaults - Cedar authorization policies Documentation Updates: - Library module documentation - Extension API guides - AI system documentation - Service management guides - Test environment setup - Plugin usage guides - Validator configuration documentation All changes are backward compatible.
1036 lines
38 KiB
HTML
1036 lines
38 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Implementation Guide - Provisioning Platform Documentation</title>
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
<meta name="description" content="Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff">
|
||
|
||
<link rel="icon" href="../favicon.svg">
|
||
<link rel="shortcut icon" href="../favicon.png">
|
||
<link rel="stylesheet" href="../css/variables.css">
|
||
<link rel="stylesheet" href="../css/general.css">
|
||
<link rel="stylesheet" href="../css/chrome.css">
|
||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
|
||
|
||
<!-- Provide site root and default themes to javascript -->
|
||
<script>
|
||
const path_to_root = "../";
|
||
const default_light_theme = "ayu";
|
||
const default_dark_theme = "navy";
|
||
</script>
|
||
<!-- Start loading toc.js asap -->
|
||
<script src="../toc.js"></script>
|
||
</head>
|
||
<body>
|
||
<div id="mdbook-help-container">
|
||
<div id="mdbook-help-popup">
|
||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||
<div>
|
||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||
<p>Press <kbd>?</kbd> to show this help</p>
|
||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div id="body-container">
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script>
|
||
try {
|
||
let theme = localStorage.getItem('mdbook-theme');
|
||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script>
|
||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||
let theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
const html = document.documentElement;
|
||
html.classList.remove('ayu')
|
||
html.classList.add(theme);
|
||
html.classList.add("js");
|
||
</script>
|
||
|
||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script>
|
||
let sidebar = null;
|
||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
} else {
|
||
sidebar = 'hidden';
|
||
}
|
||
sidebar_toggle.checked = sidebar === 'visible';
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<!-- populated by js -->
|
||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||
<noscript>
|
||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||
</noscript>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||
<div class="sidebar-resize-indicator"></div>
|
||
</div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky">
|
||
<div class="left-buttons">
|
||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</label>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">Provisioning Platform Documentation</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
<a href="https://github.com/provisioning/provisioning-platform" title="Git repository" aria-label="Git repository">
|
||
<i id="git-repository-button" class="fa fa-github"></i>
|
||
</a>
|
||
<a href="https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/development/implementation-guide.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script>
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<h1 id="repository-restructuring---implementation-guide"><a class="header" href="#repository-restructuring---implementation-guide">Repository Restructuring - Implementation Guide</a></h1>
|
||
<p><strong>Status:</strong> Ready for Implementation
|
||
<strong>Estimated Time:</strong> 12-16 days
|
||
<strong>Priority:</strong> High
|
||
<strong>Related:</strong> <a href="../architecture/repo-dist-analysis.html">Architecture Analysis</a></p>
|
||
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
||
<p>This guide provides step-by-step instructions for implementing the repository restructuring and distribution system improvements. Each phase includes specific commands, validation steps, and rollback procedures.</p>
|
||
<hr />
|
||
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
|
||
<h3 id="required-tools"><a class="header" href="#required-tools">Required Tools</a></h3>
|
||
<ul>
|
||
<li>Nushell 0.107.1+</li>
|
||
<li>Rust toolchain (for platform builds)</li>
|
||
<li>Git</li>
|
||
<li>tar/gzip</li>
|
||
<li>curl or wget</li>
|
||
</ul>
|
||
<h3 id="recommended-tools"><a class="header" href="#recommended-tools">Recommended Tools</a></h3>
|
||
<ul>
|
||
<li>Just (task runner)</li>
|
||
<li>ripgrep (for code searches)</li>
|
||
<li>fd (for file finding)</li>
|
||
</ul>
|
||
<h3 id="before-starting"><a class="header" href="#before-starting">Before Starting</a></h3>
|
||
<ol>
|
||
<li><strong>Create full backup</strong></li>
|
||
<li><strong>Notify team members</strong></li>
|
||
<li><strong>Create implementation branch</strong></li>
|
||
<li><strong>Set aside dedicated time</strong></li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="phase-1-repository-restructuring-days-1-4"><a class="header" href="#phase-1-repository-restructuring-days-1-4">Phase 1: Repository Restructuring (Days 1-4)</a></h2>
|
||
<h3 id="day-1-backup-and-analysis"><a class="header" href="#day-1-backup-and-analysis">Day 1: Backup and Analysis</a></h3>
|
||
<h4 id="step-11-create-complete-backup"><a class="header" href="#step-11-create-complete-backup">Step 1.1: Create Complete Backup</a></h4>
|
||
<pre><code class="language-bash"># Create timestamped backup
|
||
BACKUP_DIR="/Users/Akasha/project-provisioning-backup-$(date +%Y%m%d)"
|
||
cp -r /Users/Akasha/project-provisioning "$BACKUP_DIR"
|
||
|
||
# Verify backup
|
||
ls -lh "$BACKUP_DIR"
|
||
du -sh "$BACKUP_DIR"
|
||
|
||
# Create backup manifest
|
||
find "$BACKUP_DIR" -type f > "$BACKUP_DIR/manifest.txt"
|
||
echo "✅ Backup created: $BACKUP_DIR"
|
||
</code></pre>
|
||
<h4 id="step-12-analyze-current-state"><a class="header" href="#step-12-analyze-current-state">Step 1.2: Analyze Current State</a></h4>
|
||
<pre><code class="language-bash">cd /Users/Akasha/project-provisioning
|
||
|
||
# Count workspace directories
|
||
echo "=== Workspace Directories ==="
|
||
fd workspace -t d
|
||
|
||
# Analyze workspace contents
|
||
echo "=== Active Workspace ==="
|
||
du -sh workspace/
|
||
|
||
echo "=== Backup Workspaces ==="
|
||
du -sh _workspace/ backup-workspace/ workspace-librecloud/
|
||
|
||
# Find obsolete directories
|
||
echo "=== Build Artifacts ==="
|
||
du -sh target/ wrks/ NO/
|
||
|
||
# Save analysis
|
||
{
|
||
echo "# Current State Analysis - $(date)"
|
||
echo ""
|
||
echo "## Workspace Directories"
|
||
fd workspace -t d
|
||
echo ""
|
||
echo "## Directory Sizes"
|
||
du -sh workspace/ _workspace/ backup-workspace/ workspace-librecloud/ 2>/dev/null
|
||
echo ""
|
||
echo "## Build Artifacts"
|
||
du -sh target/ wrks/ NO/ 2>/dev/null
|
||
} > docs/development/current-state-analysis.txt
|
||
|
||
echo "✅ Analysis complete: docs/development/current-state-analysis.txt"
|
||
</code></pre>
|
||
<h4 id="step-13-identify-dependencies"><a class="header" href="#step-13-identify-dependencies">Step 1.3: Identify Dependencies</a></h4>
|
||
<pre><code class="language-bash"># Find all hardcoded paths
|
||
echo "=== Hardcoded Paths in Nushell Scripts ==="
|
||
rg -t nu "workspace/|_workspace/|backup-workspace/" provisioning/core/nulib/ | tee hardcoded-paths.txt
|
||
|
||
# Find ENV references (legacy)
|
||
echo "=== ENV References ==="
|
||
rg "PROVISIONING_" provisioning/core/nulib/ | wc -l
|
||
|
||
# Find workspace references in configs
|
||
echo "=== Config References ==="
|
||
rg "workspace" provisioning/config/
|
||
|
||
echo "✅ Dependencies mapped"
|
||
</code></pre>
|
||
<h4 id="step-14-create-implementation-branch"><a class="header" href="#step-14-create-implementation-branch">Step 1.4: Create Implementation Branch</a></h4>
|
||
<pre><code class="language-bash"># Create and switch to implementation branch
|
||
git checkout -b feat/repo-restructure
|
||
|
||
# Commit analysis
|
||
git add docs/development/current-state-analysis.txt
|
||
git commit -m "docs: add current state analysis for restructuring"
|
||
|
||
echo "✅ Implementation branch created: feat/repo-restructure"
|
||
</code></pre>
|
||
<p><strong>Validation:</strong></p>
|
||
<ul>
|
||
<li>✅ Backup exists and is complete</li>
|
||
<li>✅ Analysis document created</li>
|
||
<li>✅ Dependencies mapped</li>
|
||
<li>✅ Implementation branch ready</li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="day-2-directory-restructuring"><a class="header" href="#day-2-directory-restructuring">Day 2: Directory Restructuring</a></h3>
|
||
<h4 id="step-21-create-new-directory-structure"><a class="header" href="#step-21-create-new-directory-structure">Step 2.1: Create New Directory Structure</a></h4>
|
||
<pre><code class="language-bash">cd /Users/Akasha/project-provisioning
|
||
|
||
# Create distribution directory structure
|
||
mkdir -p distribution/{packages,installers,registry}
|
||
echo "✅ Created distribution/"
|
||
|
||
# Create workspace structure (keep tracked templates)
|
||
mkdir -p workspace/{infra,config,extensions,runtime}/{.gitkeep}
|
||
mkdir -p workspace/templates/{minimal,kubernetes,multi-cloud}
|
||
echo "✅ Created workspace/"
|
||
|
||
# Verify
|
||
tree -L 2 distribution/ workspace/
|
||
</code></pre>
|
||
<h4 id="step-22-move-build-artifacts"><a class="header" href="#step-22-move-build-artifacts">Step 2.2: Move Build Artifacts</a></h4>
|
||
<pre><code class="language-bash"># Move Rust build artifacts
|
||
if [ -d "target" ]; then
|
||
mv target distribution/target
|
||
echo "✅ Moved target/ to distribution/"
|
||
fi
|
||
|
||
# Move KCL packages
|
||
if [ -d "provisioning/tools/dist" ]; then
|
||
mv provisioning/tools/dist/* distribution/packages/ 2>/dev/null || true
|
||
echo "✅ Moved packages to distribution/"
|
||
fi
|
||
|
||
# Move any existing packages
|
||
find . -name "*.tar.gz" -o -name "*.zip" | grep -v node_modules | while read pkg; do
|
||
mv "$pkg" distribution/packages/
|
||
echo " Moved: $pkg"
|
||
done
|
||
</code></pre>
|
||
<h4 id="step-23-consolidate-workspaces"><a class="header" href="#step-23-consolidate-workspaces">Step 2.3: Consolidate Workspaces</a></h4>
|
||
<pre><code class="language-bash"># Identify active workspace
|
||
echo "=== Current Workspace Status ==="
|
||
ls -la workspace/ _workspace/ backup-workspace/ 2>/dev/null
|
||
|
||
# Interactive workspace consolidation
|
||
read -p "Which workspace is currently active? (workspace/_workspace/backup-workspace): " ACTIVE_WS
|
||
|
||
if [ "$ACTIVE_WS" != "workspace" ]; then
|
||
echo "Consolidating $ACTIVE_WS to workspace/"
|
||
|
||
# Merge infra configs
|
||
if [ -d "$ACTIVE_WS/infra" ]; then
|
||
cp -r "$ACTIVE_WS/infra/"* workspace/infra/
|
||
fi
|
||
|
||
# Merge configs
|
||
if [ -d "$ACTIVE_WS/config" ]; then
|
||
cp -r "$ACTIVE_WS/config/"* workspace/config/
|
||
fi
|
||
|
||
# Merge extensions
|
||
if [ -d "$ACTIVE_WS/extensions" ]; then
|
||
cp -r "$ACTIVE_WS/extensions/"* workspace/extensions/
|
||
fi
|
||
|
||
echo "✅ Consolidated workspace"
|
||
fi
|
||
|
||
# Archive old workspace directories
|
||
mkdir -p .archived-workspaces
|
||
for ws in _workspace backup-workspace workspace-librecloud; do
|
||
if [ -d "$ws" ] && [ "$ws" != "$ACTIVE_WS" ]; then
|
||
mv "$ws" ".archived-workspaces/$(basename $ws)-$(date +%Y%m%d)"
|
||
echo " Archived: $ws"
|
||
fi
|
||
done
|
||
|
||
echo "✅ Workspaces consolidated"
|
||
</code></pre>
|
||
<h4 id="step-24-remove-obsolete-directories"><a class="header" href="#step-24-remove-obsolete-directories">Step 2.4: Remove Obsolete Directories</a></h4>
|
||
<pre><code class="language-bash"># Remove build artifacts (already moved)
|
||
rm -rf wrks/
|
||
echo "✅ Removed wrks/"
|
||
|
||
# Remove test/scratch directories
|
||
rm -rf NO/
|
||
echo "✅ Removed NO/"
|
||
|
||
# Archive presentations (optional)
|
||
if [ -d "presentations" ]; then
|
||
read -p "Archive presentations directory? (y/N): " ARCHIVE_PRES
|
||
if [ "$ARCHIVE_PRES" = "y" ]; then
|
||
tar czf presentations-archive-$(date +%Y%m%d).tar.gz presentations/
|
||
rm -rf presentations/
|
||
echo "✅ Archived and removed presentations/"
|
||
fi
|
||
fi
|
||
|
||
# Remove empty directories
|
||
find . -type d -empty -delete 2>/dev/null || true
|
||
|
||
echo "✅ Cleanup complete"
|
||
</code></pre>
|
||
<h4 id="step-25-update-gitignore"><a class="header" href="#step-25-update-gitignore">Step 2.5: Update .gitignore</a></h4>
|
||
<pre><code class="language-bash"># Backup existing .gitignore
|
||
cp .gitignore .gitignore.backup
|
||
|
||
# Update .gitignore
|
||
cat >> .gitignore << 'EOF'
|
||
|
||
# ============================================================================
|
||
# Repository Restructure (2025-10-01)
|
||
# ============================================================================
|
||
|
||
# Workspace runtime data (user-specific)
|
||
/workspace/infra/
|
||
/workspace/config/
|
||
/workspace/extensions/
|
||
/workspace/runtime/
|
||
|
||
# Distribution artifacts
|
||
/distribution/packages/
|
||
/distribution/target/
|
||
|
||
# Build artifacts
|
||
/target/
|
||
/provisioning/platform/target/
|
||
/provisioning/platform/*/target/
|
||
|
||
# Rust artifacts
|
||
**/*.rs.bk
|
||
Cargo.lock
|
||
|
||
# Archived directories
|
||
/.archived-workspaces/
|
||
|
||
# Temporary files
|
||
*.tmp
|
||
*.temp
|
||
/tmp/
|
||
/wrks/
|
||
/NO/
|
||
|
||
# Logs
|
||
*.log
|
||
/workspace/runtime/logs/
|
||
|
||
# Cache
|
||
.cache/
|
||
/workspace/runtime/cache/
|
||
|
||
# IDE
|
||
.vscode/
|
||
.idea/
|
||
*.swp
|
||
*.swo
|
||
*~
|
||
|
||
# OS
|
||
.DS_Store
|
||
Thumbs.db
|
||
|
||
# Backup files
|
||
*.backup
|
||
*.bak
|
||
|
||
EOF
|
||
|
||
echo "✅ Updated .gitignore"
|
||
</code></pre>
|
||
<h4 id="step-26-commit-restructuring"><a class="header" href="#step-26-commit-restructuring">Step 2.6: Commit Restructuring</a></h4>
|
||
<pre><code class="language-bash"># Stage changes
|
||
git add -A
|
||
|
||
# Show what's being committed
|
||
git status
|
||
|
||
# Commit
|
||
git commit -m "refactor: restructure repository for clean distribution
|
||
|
||
- Consolidate workspace directories to single workspace/
|
||
- Move build artifacts to distribution/
|
||
- Remove obsolete directories (wrks/, NO/)
|
||
- Update .gitignore for new structure
|
||
- Archive old workspace variants
|
||
|
||
This is part of Phase 1 of the repository restructuring plan.
|
||
|
||
Related: docs/architecture/repo-dist-analysis.md"
|
||
|
||
echo "✅ Restructuring committed"
|
||
</code></pre>
|
||
<p><strong>Validation:</strong></p>
|
||
<ul>
|
||
<li>✅ Single <code>workspace/</code> directory exists</li>
|
||
<li>✅ Build artifacts in <code>distribution/</code></li>
|
||
<li>✅ No <code>wrks/</code>, <code>NO/</code> directories</li>
|
||
<li>✅ <code>.gitignore</code> updated</li>
|
||
<li>✅ Changes committed</li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="day-3-update-path-references"><a class="header" href="#day-3-update-path-references">Day 3: Update Path References</a></h3>
|
||
<h4 id="step-31-create-path-update-script"><a class="header" href="#step-31-create-path-update-script">Step 3.1: Create Path Update Script</a></h4>
|
||
<pre><code class="language-bash"># Create migration script
|
||
cat > provisioning/tools/migration/update-paths.nu << 'EOF'
|
||
#!/usr/bin/env nu
|
||
# Path update script for repository restructuring
|
||
|
||
# Find and replace path references
|
||
export def main [] {
|
||
print "🔧 Updating path references..."
|
||
|
||
let replacements = [
|
||
["_workspace/" "workspace/"]
|
||
["backup-workspace/" "workspace/"]
|
||
["workspace-librecloud/" "workspace/"]
|
||
["wrks/" "distribution/"]
|
||
["NO/" "distribution/"]
|
||
]
|
||
|
||
let files = (fd -e nu -e toml -e md . provisioning/)
|
||
|
||
mut updated_count = 0
|
||
|
||
for file in $files {
|
||
mut content = (open $file)
|
||
mut modified = false
|
||
|
||
for replacement in $replacements {
|
||
let old = $replacement.0
|
||
let new = $replacement.1
|
||
|
||
if ($content | str contains $old) {
|
||
$content = ($content | str replace -a $old $new)
|
||
$modified = true
|
||
}
|
||
}
|
||
|
||
if $modified {
|
||
$content | save -f $file
|
||
$updated_count = $updated_count + 1
|
||
print $" ✓ Updated: ($file)"
|
||
}
|
||
}
|
||
|
||
print $"✅ Updated ($updated_count) files"
|
||
}
|
||
EOF
|
||
|
||
chmod +x provisioning/tools/migration/update-paths.nu
|
||
</code></pre>
|
||
<h4 id="step-32-run-path-updates"><a class="header" href="#step-32-run-path-updates">Step 3.2: Run Path Updates</a></h4>
|
||
<pre><code class="language-bash"># Create backup before updates
|
||
git stash
|
||
git checkout -b feat/path-updates
|
||
|
||
# Run update script
|
||
nu provisioning/tools/migration/update-paths.nu
|
||
|
||
# Review changes
|
||
git diff
|
||
|
||
# Test a sample file
|
||
nu -c "use provisioning/core/nulib/servers/create.nu; print 'OK'"
|
||
</code></pre>
|
||
<h4 id="step-33-update-claudemd"><a class="header" href="#step-33-update-claudemd">Step 3.3: Update CLAUDE.md</a></h4>
|
||
<pre><code class="language-bash"># Update CLAUDE.md with new paths
|
||
cat > CLAUDE.md.new << 'EOF'
|
||
# CLAUDE.md
|
||
|
||
[Keep existing content, update paths section...]
|
||
|
||
## Updated Path Structure (2025-10-01)
|
||
|
||
### Core System
|
||
- **Main CLI**: `provisioning/core/cli/provisioning`
|
||
- **Libraries**: `provisioning/core/nulib/`
|
||
- **Extensions**: `provisioning/extensions/`
|
||
- **Platform**: `provisioning/platform/`
|
||
|
||
### User Workspace
|
||
- **Active Workspace**: `workspace/` (gitignored runtime data)
|
||
- **Templates**: `workspace/templates/` (tracked)
|
||
- **Infrastructure**: `workspace/infra/` (user configs, gitignored)
|
||
|
||
### Build System
|
||
- **Distribution**: `distribution/` (gitignored artifacts)
|
||
- **Packages**: `distribution/packages/`
|
||
- **Installers**: `distribution/installers/`
|
||
|
||
[Continue with rest of content...]
|
||
EOF
|
||
|
||
# Review changes
|
||
diff CLAUDE.md CLAUDE.md.new
|
||
|
||
# Apply if satisfied
|
||
mv CLAUDE.md.new CLAUDE.md
|
||
</code></pre>
|
||
<h4 id="step-34-update-documentation"><a class="header" href="#step-34-update-documentation">Step 3.4: Update Documentation</a></h4>
|
||
<pre><code class="language-bash"># Find all documentation files
|
||
fd -e md . docs/
|
||
|
||
# Update each doc with new paths
|
||
# This is semi-automated - review each file
|
||
|
||
# Create list of docs to update
|
||
fd -e md . docs/ > docs-to-update.txt
|
||
|
||
# Manual review and update
|
||
echo "Review and update each documentation file with new paths"
|
||
echo "Files listed in: docs-to-update.txt"
|
||
</code></pre>
|
||
<h4 id="step-35-commit-path-updates"><a class="header" href="#step-35-commit-path-updates">Step 3.5: Commit Path Updates</a></h4>
|
||
<pre><code class="language-bash">git add -A
|
||
git commit -m "refactor: update all path references for new structure
|
||
|
||
- Update Nushell scripts to use workspace/ instead of variants
|
||
- Update CLAUDE.md with new path structure
|
||
- Update documentation references
|
||
- Add migration script for future path changes
|
||
|
||
Phase 1.3 of repository restructuring."
|
||
|
||
echo "✅ Path updates committed"
|
||
</code></pre>
|
||
<p><strong>Validation:</strong></p>
|
||
<ul>
|
||
<li>✅ All Nushell scripts reference correct paths</li>
|
||
<li>✅ CLAUDE.md updated</li>
|
||
<li>✅ Documentation updated</li>
|
||
<li>✅ No references to old paths remain</li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="day-4-validation-and-testing"><a class="header" href="#day-4-validation-and-testing">Day 4: Validation and Testing</a></h3>
|
||
<h4 id="step-41-automated-validation"><a class="header" href="#step-41-automated-validation">Step 4.1: Automated Validation</a></h4>
|
||
<pre><code class="language-bash"># Create validation script
|
||
cat > provisioning/tools/validation/validate-structure.nu << 'EOF'
|
||
#!/usr/bin/env nu
|
||
# Repository structure validation
|
||
|
||
export def main [] {
|
||
print "🔍 Validating repository structure..."
|
||
|
||
mut passed = 0
|
||
mut failed = 0
|
||
|
||
# Check required directories exist
|
||
let required_dirs = [
|
||
"provisioning/core"
|
||
"provisioning/extensions"
|
||
"provisioning/platform"
|
||
"provisioning/kcl"
|
||
"workspace"
|
||
"workspace/templates"
|
||
"distribution"
|
||
"docs"
|
||
"tests"
|
||
]
|
||
|
||
for dir in $required_dirs {
|
||
if ($dir | path exists) {
|
||
print $" ✓ ($dir)"
|
||
$passed = $passed + 1
|
||
} else {
|
||
print $" ✗ ($dir) MISSING"
|
||
$failed = $failed + 1
|
||
}
|
||
}
|
||
|
||
# Check obsolete directories don't exist
|
||
let obsolete_dirs = [
|
||
"_workspace"
|
||
"backup-workspace"
|
||
"workspace-librecloud"
|
||
"wrks"
|
||
"NO"
|
||
]
|
||
|
||
for dir in $obsolete_dirs {
|
||
if not ($dir | path exists) {
|
||
print $" ✓ ($dir) removed"
|
||
$passed = $passed + 1
|
||
} else {
|
||
print $" ✗ ($dir) still exists"
|
||
$failed = $failed + 1
|
||
}
|
||
}
|
||
|
||
# Check no old path references
|
||
let old_paths = ["_workspace/" "backup-workspace/" "wrks/"]
|
||
for path in $old_paths {
|
||
let results = (rg -l $path provisioning/ --iglob "!*.md" 2>/dev/null | lines)
|
||
if ($results | is-empty) {
|
||
print $" ✓ No references to ($path)"
|
||
$passed = $passed + 1
|
||
} else {
|
||
print $" ✗ Found references to ($path):"
|
||
$results | each { |f| print $" - ($f)" }
|
||
$failed = $failed + 1
|
||
}
|
||
}
|
||
|
||
print ""
|
||
print $"Results: ($passed) passed, ($failed) failed"
|
||
|
||
if $failed > 0 {
|
||
error make { msg: "Validation failed" }
|
||
}
|
||
|
||
print "✅ Validation passed"
|
||
}
|
||
EOF
|
||
|
||
chmod +x provisioning/tools/validation/validate-structure.nu
|
||
|
||
# Run validation
|
||
nu provisioning/tools/validation/validate-structure.nu
|
||
</code></pre>
|
||
<h4 id="step-42-functional-testing"><a class="header" href="#step-42-functional-testing">Step 4.2: Functional Testing</a></h4>
|
||
<pre><code class="language-bash"># Test core commands
|
||
echo "=== Testing Core Commands ==="
|
||
|
||
# Version
|
||
provisioning/core/cli/provisioning version
|
||
echo "✓ version command"
|
||
|
||
# Help
|
||
provisioning/core/cli/provisioning help
|
||
echo "✓ help command"
|
||
|
||
# List
|
||
provisioning/core/cli/provisioning list servers
|
||
echo "✓ list command"
|
||
|
||
# Environment
|
||
provisioning/core/cli/provisioning env
|
||
echo "✓ env command"
|
||
|
||
# Validate config
|
||
provisioning/core/cli/provisioning validate config
|
||
echo "✓ validate command"
|
||
|
||
echo "✅ Functional tests passed"
|
||
</code></pre>
|
||
<h4 id="step-43-integration-testing"><a class="header" href="#step-43-integration-testing">Step 4.3: Integration Testing</a></h4>
|
||
<pre><code class="language-bash"># Test workflow system
|
||
echo "=== Testing Workflow System ==="
|
||
|
||
# List workflows
|
||
nu -c "use provisioning/core/nulib/workflows/management.nu *; workflow list"
|
||
echo "✓ workflow list"
|
||
|
||
# Test workspace commands
|
||
echo "=== Testing Workspace Commands ==="
|
||
|
||
# Workspace info
|
||
provisioning/core/cli/provisioning workspace info
|
||
echo "✓ workspace info"
|
||
|
||
echo "✅ Integration tests passed"
|
||
</code></pre>
|
||
<h4 id="step-44-create-test-report"><a class="header" href="#step-44-create-test-report">Step 4.4: Create Test Report</a></h4>
|
||
<pre><code class="language-bash">{
|
||
echo "# Repository Restructuring - Validation Report"
|
||
echo "Date: $(date)"
|
||
echo ""
|
||
echo "## Structure Validation"
|
||
nu provisioning/tools/validation/validate-structure.nu 2>&1
|
||
echo ""
|
||
echo "## Functional Tests"
|
||
echo "✓ version command"
|
||
echo "✓ help command"
|
||
echo "✓ list command"
|
||
echo "✓ env command"
|
||
echo "✓ validate command"
|
||
echo ""
|
||
echo "## Integration Tests"
|
||
echo "✓ workflow list"
|
||
echo "✓ workspace info"
|
||
echo ""
|
||
echo "## Conclusion"
|
||
echo "✅ Phase 1 validation complete"
|
||
} > docs/development/phase1-validation-report.md
|
||
|
||
echo "✅ Test report created: docs/development/phase1-validation-report.md"
|
||
</code></pre>
|
||
<h4 id="step-45-update-readme"><a class="header" href="#step-45-update-readme">Step 4.5: Update README</a></h4>
|
||
<pre><code class="language-bash"># Update main README with new structure
|
||
# This is manual - review and update README.md
|
||
|
||
echo "📝 Please review and update README.md with new structure"
|
||
echo " - Update directory structure diagram"
|
||
echo " - Update installation instructions"
|
||
echo " - Update quick start guide"
|
||
</code></pre>
|
||
<h4 id="step-46-finalize-phase-1"><a class="header" href="#step-46-finalize-phase-1">Step 4.6: Finalize Phase 1</a></h4>
|
||
<pre><code class="language-bash"># Commit validation and reports
|
||
git add -A
|
||
git commit -m "test: add validation for repository restructuring
|
||
|
||
- Add structure validation script
|
||
- Add functional tests
|
||
- Add integration tests
|
||
- Create validation report
|
||
- Document Phase 1 completion
|
||
|
||
Phase 1 complete: Repository restructuring validated."
|
||
|
||
# Merge to implementation branch
|
||
git checkout feat/repo-restructure
|
||
git merge feat/path-updates
|
||
|
||
echo "✅ Phase 1 complete and merged"
|
||
</code></pre>
|
||
<p><strong>Validation:</strong></p>
|
||
<ul>
|
||
<li>✅ All validation tests pass</li>
|
||
<li>✅ Functional tests pass</li>
|
||
<li>✅ Integration tests pass</li>
|
||
<li>✅ Validation report created</li>
|
||
<li>✅ README updated</li>
|
||
<li>✅ Phase 1 changes merged</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="phase-2-build-system-implementation-days-5-8"><a class="header" href="#phase-2-build-system-implementation-days-5-8">Phase 2: Build System Implementation (Days 5-8)</a></h2>
|
||
<h3 id="day-5-build-system-core"><a class="header" href="#day-5-build-system-core">Day 5: Build System Core</a></h3>
|
||
<h4 id="step-51-create-build-tools-directory"><a class="header" href="#step-51-create-build-tools-directory">Step 5.1: Create Build Tools Directory</a></h4>
|
||
<pre><code class="language-bash">mkdir -p provisioning/tools/build
|
||
cd provisioning/tools/build
|
||
|
||
# Create directory structure
|
||
mkdir -p {core,platform,extensions,validation,distribution}
|
||
|
||
echo "✅ Build tools directory created"
|
||
</code></pre>
|
||
<h4 id="step-52-implement-core-build-system"><a class="header" href="#step-52-implement-core-build-system">Step 5.2: Implement Core Build System</a></h4>
|
||
<pre><code class="language-bash"># Create main build orchestrator
|
||
# See full implementation in repo-dist-analysis.md
|
||
# Copy build-system.nu from the analysis document
|
||
|
||
# Test build system
|
||
nu build-system.nu status
|
||
</code></pre>
|
||
<h4 id="step-53-implement-core-packaging"><a class="header" href="#step-53-implement-core-packaging">Step 5.3: Implement Core Packaging</a></h4>
|
||
<pre><code class="language-bash"># Create package-core.nu
|
||
# This packages Nushell libraries, KCL schemas, templates
|
||
|
||
# Test core packaging
|
||
nu build-system.nu build-core --version dev
|
||
</code></pre>
|
||
<h4 id="step-54-create-justfile"><a class="header" href="#step-54-create-justfile">Step 5.4: Create Justfile</a></h4>
|
||
<pre><code class="language-bash"># Create Justfile in project root
|
||
# See full Justfile in repo-dist-analysis.md
|
||
|
||
# Test Justfile
|
||
just --list
|
||
just status
|
||
</code></pre>
|
||
<p><strong>Validation:</strong></p>
|
||
<ul>
|
||
<li>✅ Build system structure exists</li>
|
||
<li>✅ Core build orchestrator works</li>
|
||
<li>✅ Core packaging works</li>
|
||
<li>✅ Justfile functional</li>
|
||
</ul>
|
||
<h3 id="day-6-8-continue-with-platform-extensions-and-validation"><a class="header" href="#day-6-8-continue-with-platform-extensions-and-validation">Day 6-8: Continue with Platform, Extensions, and Validation</a></h3>
|
||
<p>[Follow similar pattern for remaining build system components]</p>
|
||
<hr />
|
||
<h2 id="phase-3-installation-system-days-9-11"><a class="header" href="#phase-3-installation-system-days-9-11">Phase 3: Installation System (Days 9-11)</a></h2>
|
||
<h3 id="day-9-nushell-installer"><a class="header" href="#day-9-nushell-installer">Day 9: Nushell Installer</a></h3>
|
||
<h4 id="step-91-create-installnu"><a class="header" href="#step-91-create-installnu">Step 9.1: Create install.nu</a></h4>
|
||
<pre><code class="language-bash">mkdir -p distribution/installers
|
||
|
||
# Create install.nu
|
||
# See full implementation in repo-dist-analysis.md
|
||
</code></pre>
|
||
<h4 id="step-92-test-installation"><a class="header" href="#step-92-test-installation">Step 9.2: Test Installation</a></h4>
|
||
<pre><code class="language-bash"># Test installation to /tmp
|
||
nu distribution/installers/install.nu --prefix /tmp/provisioning-test
|
||
|
||
# Verify
|
||
ls -lh /tmp/provisioning-test/
|
||
|
||
# Test uninstallation
|
||
nu distribution/installers/install.nu uninstall --prefix /tmp/provisioning-test
|
||
</code></pre>
|
||
<p><strong>Validation:</strong></p>
|
||
<ul>
|
||
<li>✅ Installer works</li>
|
||
<li>✅ Files installed to correct locations</li>
|
||
<li>✅ Uninstaller works</li>
|
||
<li>✅ No files left after uninstall</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="rollback-procedures"><a class="header" href="#rollback-procedures">Rollback Procedures</a></h2>
|
||
<h3 id="if-phase-1-fails"><a class="header" href="#if-phase-1-fails">If Phase 1 Fails</a></h3>
|
||
<pre><code class="language-bash"># Restore from backup
|
||
rm -rf /Users/Akasha/project-provisioning
|
||
cp -r "$BACKUP_DIR" /Users/Akasha/project-provisioning
|
||
|
||
# Return to main branch
|
||
cd /Users/Akasha/project-provisioning
|
||
git checkout main
|
||
git branch -D feat/repo-restructure
|
||
</code></pre>
|
||
<h3 id="if-build-system-fails"><a class="header" href="#if-build-system-fails">If Build System Fails</a></h3>
|
||
<pre><code class="language-bash"># Revert build system commits
|
||
git checkout feat/repo-restructure
|
||
git revert <commit-hash>
|
||
</code></pre>
|
||
<h3 id="if-installation-fails"><a class="header" href="#if-installation-fails">If Installation Fails</a></h3>
|
||
<pre><code class="language-bash"># Clean up test installation
|
||
rm -rf /tmp/provisioning-test
|
||
sudo rm -rf /usr/local/lib/provisioning
|
||
sudo rm -rf /usr/local/share/provisioning
|
||
</code></pre>
|
||
<hr />
|
||
<h2 id="checklist"><a class="header" href="#checklist">Checklist</a></h2>
|
||
<h3 id="phase-1-repository-restructuring"><a class="header" href="#phase-1-repository-restructuring">Phase 1: Repository Restructuring</a></h3>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 1: Backup and analysis complete</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 2: Directory restructuring complete</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 3: Path references updated</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 4: Validation passed</li>
|
||
</ul>
|
||
<h3 id="phase-2-build-system"><a class="header" href="#phase-2-build-system">Phase 2: Build System</a></h3>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 5: Core build system implemented</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 6: Platform/extensions packaging</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 7: Package validation</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 8: Build system tested</li>
|
||
</ul>
|
||
<h3 id="phase-3-installation"><a class="header" href="#phase-3-installation">Phase 3: Installation</a></h3>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 9: Nushell installer created</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 10: Bash installer and CLI</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 11: Multi-OS testing</li>
|
||
</ul>
|
||
<h3 id="phase-4-registry-optional"><a class="header" href="#phase-4-registry-optional">Phase 4: Registry (Optional)</a></h3>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 12: Registry system</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 13: Registry commands</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 14: Registry hosting</li>
|
||
</ul>
|
||
<h3 id="phase-5-documentation"><a class="header" href="#phase-5-documentation">Phase 5: Documentation</a></h3>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 15: Documentation updated</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Day 16: Release prepared</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="notes"><a class="header" href="#notes">Notes</a></h2>
|
||
<ul>
|
||
<li><strong>Take breaks between phases</strong> - Don’t rush</li>
|
||
<li><strong>Test thoroughly</strong> - Each phase builds on previous</li>
|
||
<li><strong>Commit frequently</strong> - Small, atomic commits</li>
|
||
<li><strong>Document issues</strong> - Track any problems encountered</li>
|
||
<li><strong>Ask for review</strong> - Get feedback at phase boundaries</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="support"><a class="header" href="#support">Support</a></h2>
|
||
<p>If you encounter issues:</p>
|
||
<ol>
|
||
<li>Check the validation reports</li>
|
||
<li>Review the rollback procedures</li>
|
||
<li>Consult the architecture analysis</li>
|
||
<li>Create an issue in the tracker</li>
|
||
</ol>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="../development/integration.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next prefetch" href="../development/distribution-process.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
<a rel="prev" href="../development/integration.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next prefetch" href="../development/distribution-process.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
<!-- Livereload script (if served using the cli tool) -->
|
||
<script>
|
||
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
||
const socket = new WebSocket(wsAddress);
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
<script>
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="../elasticlunr.min.js"></script>
|
||
<script src="../mark.min.js"></script>
|
||
<script src="../searcher.js"></script>
|
||
|
||
<script src="../clipboard.min.js"></script>
|
||
<script src="../highlight.js"></script>
|
||
<script src="../book.js"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|