feat: schedule local workspace verification
This commit is contained in:
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,5 +1,6 @@
|
||||
/node_modules/
|
||||
/.build/
|
||||
/workspace.local.yml
|
||||
/.local/
|
||||
*.tmp
|
||||
*.bak
|
||||
|
||||
52
Jenkinsfile
vendored
52
Jenkinsfile
vendored
@@ -1,52 +0,0 @@
|
||||
pipeline {
|
||||
agent { label 'agent-harness' }
|
||||
|
||||
options {
|
||||
disableConcurrentBuilds()
|
||||
skipDefaultCheckout(true)
|
||||
timestamps()
|
||||
}
|
||||
|
||||
triggers {
|
||||
cron('TZ=Asia/Seoul\nH 8 * * 1-5')
|
||||
}
|
||||
|
||||
stages {
|
||||
stage('Verify Workspace') {
|
||||
steps {
|
||||
powershell '''
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
if ([string]::IsNullOrWhiteSpace($env:KRI_DEV_ROOT)) {
|
||||
throw 'KRI_DEV_ROOT must point to the existing KRI multi-repository workspace root.'
|
||||
}
|
||||
|
||||
$harnessRoot = Join-Path $env:KRI_DEV_ROOT '_________AgentHarnessBase'
|
||||
$verificationScript = [System.IO.Path]::Combine(
|
||||
$harnessRoot,
|
||||
'scripts',
|
||||
'verify-workspace.ps1'
|
||||
)
|
||||
|
||||
if (-not (Test-Path -LiteralPath $verificationScript -PathType Leaf)) {
|
||||
throw "Workspace verification script not found: $verificationScript"
|
||||
}
|
||||
|
||||
& $verificationScript -WorkspaceRoot $env:KRI_DEV_ROOT
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
exit $LASTEXITCODE
|
||||
}
|
||||
'''
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
post {
|
||||
success {
|
||||
echo 'All registered Agent Harness documents are current.'
|
||||
}
|
||||
failure {
|
||||
echo 'Agent Harness drift or an invalid workspace registration was detected.'
|
||||
}
|
||||
}
|
||||
}
|
||||
17
README.md
17
README.md
@@ -65,4 +65,19 @@ Run a read-only verification of every shared and local project registration from
|
||||
npm.cmd run verify:workspace
|
||||
```
|
||||
|
||||
This command uses the committed runtime bundle and does not compose documents, update Git repositories, or access the network. The Jenkins pipeline runs the same script on the dedicated Windows workspace node. See [docs/jenkins.md](docs/jenkins.md) for node configuration, scheduling, and failure handling.
|
||||
This command uses the committed runtime bundle and does not compose documents, update Git repositories, or access the network.
|
||||
|
||||
To retain a local UTF-8 log for the same verification:
|
||||
|
||||
```powershell
|
||||
npm.cmd run verify:scheduled
|
||||
```
|
||||
|
||||
Install or remove the weekday Windows scheduled task with:
|
||||
|
||||
```powershell
|
||||
npm.cmd run schedule:install
|
||||
npm.cmd run schedule:uninstall
|
||||
```
|
||||
|
||||
See [docs/local-scheduling.md](docs/local-scheduling.md) for scheduling, log retention, and failure handling.
|
||||
|
||||
@@ -1,56 +0,0 @@
|
||||
# Jenkins Workspace Verification
|
||||
|
||||
The root `Jenkinsfile` runs a read-only `verify --all` against the existing Windows multi-repository workspace. It detects stale generated documents, missing registered repositories, invalid profiles, and contract composition failures. It never composes files or performs Git operations.
|
||||
|
||||
## Windows node setup
|
||||
|
||||
Configure one Jenkins Windows node with:
|
||||
|
||||
- the label `agent-harness`;
|
||||
- Node.js 20 or newer on `PATH`;
|
||||
- every registered repository available in the established workspace layout;
|
||||
- the node environment variable `KRI_DEV_ROOT` set to the absolute multi-repository workspace root.
|
||||
|
||||
Do not store the absolute workspace path, credentials, or tokens in this repository. The node-level environment variable owns the machine-specific path.
|
||||
|
||||
The local central harness clone must remain at `_________AgentHarnessBase` directly below `KRI_DEV_ROOT`. The pipeline deliberately skips the default Jenkins checkout and reads this existing clone so the relative paths in `workspace.yml` resolve to the sibling repositories.
|
||||
|
||||
## Jenkins job setup
|
||||
|
||||
Create a Pipeline job using Pipeline script from SCM:
|
||||
|
||||
- repository: the central Agent Harness repository;
|
||||
- branch: `master`;
|
||||
- script path: `Jenkinsfile`.
|
||||
|
||||
Assign the job only to the node carrying the `agent-harness` label. The pipeline runs automatically once per weekday at a hashed minute during the 08:00 hour in `Asia/Seoul`, and it may also be run manually.
|
||||
|
||||
The job does not fetch or update the repositories under `KRI_DEV_ROOT`. Keep that workspace synchronized using the existing repository update process before relying on the scheduled result.
|
||||
|
||||
## Local verification
|
||||
|
||||
From the central harness repository:
|
||||
|
||||
```powershell
|
||||
npm.cmd run verify:workspace
|
||||
```
|
||||
|
||||
To supply the workspace root explicitly:
|
||||
|
||||
```powershell
|
||||
.\scripts\verify-workspace.ps1 -WorkspaceRoot <workspace-root>
|
||||
```
|
||||
|
||||
Both forms execute the committed `dist\cli.cjs` bundle and require no package installation.
|
||||
|
||||
## Failure handling
|
||||
|
||||
Treat a failed build as a drift report, not as authorization for automatic repair:
|
||||
|
||||
1. identify the missing, invalid, or stale project in the console output;
|
||||
2. update the authoritative `.agent` source when a rule changed;
|
||||
3. run `plan` and obtain approval for the affected repositories;
|
||||
4. run the narrowest applicable `compose` command;
|
||||
5. run `verify` again and commit each repository independently after approval.
|
||||
|
||||
The Jenkins job must not compose documents, commit, push, pull, fetch, or modify credentials.
|
||||
54
docs/local-scheduling.md
Normal file
54
docs/local-scheduling.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Local Scheduled Workspace Verification
|
||||
|
||||
The Windows Task Scheduler runs the same read-only workspace verification as the manual command. It does not compose documents, update repositories, perform Git operations, or access the network.
|
||||
|
||||
## Manual verification with a retained log
|
||||
|
||||
Run the scheduled-verification wrapper directly before registering the task:
|
||||
|
||||
```powershell
|
||||
npm.cmd run verify:scheduled
|
||||
```
|
||||
|
||||
Each execution stores a UTF-8 log below `.local/verification-logs`. The directory is ignored by Git, and logs older than 30 days are removed after an execution finishes.
|
||||
|
||||
## Register the weekday task
|
||||
|
||||
Register the task for the current Windows user:
|
||||
|
||||
```powershell
|
||||
npm.cmd run schedule:install
|
||||
```
|
||||
|
||||
The default task is named `KRI Agent Harness Workspace Verify` and runs Monday through Friday at 08:30. It uses one process at a time, retries a failed task up to three times, and runs a missed schedule when the signed-in user becomes available.
|
||||
|
||||
The task uses an interactive, limited Windows principal. The computer must be running and the registered user must be signed in before the process can execute.
|
||||
|
||||
To use a different time, call the registration script directly with an `HH:mm` value:
|
||||
|
||||
```powershell
|
||||
.\scripts\register-scheduled-verification.ps1 -At <HH:mm>
|
||||
```
|
||||
|
||||
## Remove the task
|
||||
|
||||
```powershell
|
||||
npm.cmd run schedule:uninstall
|
||||
```
|
||||
|
||||
Removing the task does not remove retained verification logs.
|
||||
|
||||
## Result handling
|
||||
|
||||
Task Scheduler records the verification process exit code:
|
||||
|
||||
- `0`: all registered Agent Harness documents are current;
|
||||
- non-zero: a missing repository, invalid profile, stale generated document, or another verification error was detected.
|
||||
|
||||
Treat a failed task as a drift report, not as authorization for automatic repair:
|
||||
|
||||
1. inspect the newest log in `.local/verification-logs`;
|
||||
2. update the authoritative `.agent` source when a rule changed;
|
||||
3. run `plan` and obtain approval for affected repositories;
|
||||
4. run the narrowest applicable `compose` command;
|
||||
5. run the verification again and commit each repository independently after approval.
|
||||
@@ -14,7 +14,10 @@
|
||||
"typecheck": "tsc -p tsconfig.json --noEmit",
|
||||
"test": "node --test",
|
||||
"verify": "npm run typecheck && npm run build && npm test",
|
||||
"verify:workspace": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/verify-workspace.ps1"
|
||||
"verify:workspace": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/verify-workspace.ps1",
|
||||
"verify:scheduled": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/run-scheduled-verification.ps1",
|
||||
"schedule:install": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/register-scheduled-verification.ps1",
|
||||
"schedule:uninstall": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/register-scheduled-verification.ps1 -Unregister"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=20"
|
||||
|
||||
100
scripts/register-scheduled-verification.ps1
Normal file
100
scripts/register-scheduled-verification.ps1
Normal file
@@ -0,0 +1,100 @@
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $TaskName = 'KRI Agent Harness Workspace Verify',
|
||||
[string] $At = '08:30',
|
||||
[string] $WorkspaceRoot,
|
||||
[switch] $Unregister
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$harnessRoot = Split-Path -Parent $scriptRoot
|
||||
$runnerScript = Join-Path $scriptRoot 'run-scheduled-verification.ps1'
|
||||
|
||||
if ($Unregister) {
|
||||
$existingTask = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
|
||||
if ($null -eq $existingTask) {
|
||||
Write-Host "Scheduled task is not registered: $TaskName"
|
||||
exit 0
|
||||
}
|
||||
|
||||
Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false
|
||||
Write-Host "Scheduled task removed: $TaskName"
|
||||
exit 0
|
||||
}
|
||||
|
||||
if ([string]::IsNullOrWhiteSpace($WorkspaceRoot)) {
|
||||
$WorkspaceRoot = Split-Path -Parent $harnessRoot
|
||||
}
|
||||
|
||||
$scheduledTime = [TimeSpan]::Zero
|
||||
if (-not [TimeSpan]::TryParseExact(
|
||||
$At,
|
||||
'hh\:mm',
|
||||
[System.Globalization.CultureInfo]::InvariantCulture,
|
||||
[ref] $scheduledTime
|
||||
)) {
|
||||
throw "Scheduled time must use HH:mm format. Found: $At"
|
||||
}
|
||||
|
||||
$resolvedWorkspaceRoot = [System.IO.Path]::GetFullPath($WorkspaceRoot)
|
||||
$expectedHarnessRoot = [System.IO.Path]::GetFullPath(
|
||||
(Join-Path $resolvedWorkspaceRoot '_________AgentHarnessBase')
|
||||
)
|
||||
$resolvedHarnessRoot = [System.IO.Path]::GetFullPath($harnessRoot)
|
||||
|
||||
if (-not $resolvedHarnessRoot.Equals(
|
||||
$expectedHarnessRoot,
|
||||
[System.StringComparison]::OrdinalIgnoreCase
|
||||
)) {
|
||||
throw "Harness repository must be a direct child of the configured workspace root. Expected: $expectedHarnessRoot"
|
||||
}
|
||||
|
||||
if (-not (Test-Path -LiteralPath $runnerScript -PathType Leaf)) {
|
||||
throw "Scheduled verification runner not found: $runnerScript"
|
||||
}
|
||||
|
||||
$account = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
|
||||
$powershellCommand = Join-Path $PSHOME 'powershell.exe'
|
||||
$actionArguments = @(
|
||||
'-NoProfile'
|
||||
'-NonInteractive'
|
||||
'-ExecutionPolicy Bypass'
|
||||
"-File `"$runnerScript`""
|
||||
"-WorkspaceRoot `"$resolvedWorkspaceRoot`""
|
||||
) -join ' '
|
||||
|
||||
$action = New-ScheduledTaskAction `
|
||||
-Execute $powershellCommand `
|
||||
-Argument $actionArguments `
|
||||
-WorkingDirectory $resolvedHarnessRoot
|
||||
$trigger = New-ScheduledTaskTrigger `
|
||||
-Weekly `
|
||||
-WeeksInterval 1 `
|
||||
-DaysOfWeek Monday, Tuesday, Wednesday, Thursday, Friday `
|
||||
-At ([DateTime]::Today.Add($scheduledTime))
|
||||
$principal = New-ScheduledTaskPrincipal `
|
||||
-UserId $account `
|
||||
-LogonType Interactive `
|
||||
-RunLevel Limited
|
||||
$settings = New-ScheduledTaskSettingsSet `
|
||||
-StartWhenAvailable `
|
||||
-MultipleInstances IgnoreNew `
|
||||
-RestartCount 3 `
|
||||
-RestartInterval (New-TimeSpan -Minutes 10) `
|
||||
-ExecutionTimeLimit (New-TimeSpan -Hours 1)
|
||||
|
||||
Register-ScheduledTask `
|
||||
-TaskName $TaskName `
|
||||
-Action $action `
|
||||
-Trigger $trigger `
|
||||
-Principal $principal `
|
||||
-Settings $settings `
|
||||
-Description 'Runs the read-only KRI Agent Harness workspace verification and stores a local log.' `
|
||||
-Force | Out-Null
|
||||
|
||||
Write-Host "Scheduled task registered: $TaskName"
|
||||
Write-Host "User: $account"
|
||||
Write-Host "Schedule: Monday-Friday $At"
|
||||
Write-Host "Workspace: $resolvedWorkspaceRoot"
|
||||
89
scripts/run-scheduled-verification.ps1
Normal file
89
scripts/run-scheduled-verification.ps1
Normal file
@@ -0,0 +1,89 @@
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $WorkspaceRoot,
|
||||
[string] $LogDirectory,
|
||||
[ValidateRange(1, 3650)]
|
||||
[int] $RetentionDays = 30
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$harnessRoot = Split-Path -Parent $scriptRoot
|
||||
$verificationScript = Join-Path $scriptRoot 'verify-workspace.ps1'
|
||||
|
||||
if ([string]::IsNullOrWhiteSpace($WorkspaceRoot)) {
|
||||
$WorkspaceRoot = Split-Path -Parent $harnessRoot
|
||||
}
|
||||
|
||||
$resolvedWorkspaceRoot = [System.IO.Path]::GetFullPath($WorkspaceRoot)
|
||||
|
||||
if ([string]::IsNullOrWhiteSpace($LogDirectory)) {
|
||||
$LogDirectory = Join-Path $harnessRoot '.local\verification-logs'
|
||||
}
|
||||
|
||||
$resolvedLogDirectory = [System.IO.Path]::GetFullPath($LogDirectory)
|
||||
[System.IO.Directory]::CreateDirectory($resolvedLogDirectory) | Out-Null
|
||||
|
||||
$timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
|
||||
$logFile = Join-Path $resolvedLogDirectory "verify-$timestamp.log"
|
||||
$utf8WithoutBom = [System.Text.UTF8Encoding]::new($false)
|
||||
$logWriter = [System.IO.StreamWriter]::new($logFile, $false, $utf8WithoutBom)
|
||||
$exitCode = 1
|
||||
|
||||
function Write-VerificationLogLine {
|
||||
param([AllowEmptyString()][string] $Line)
|
||||
|
||||
Write-Host $Line
|
||||
$logWriter.WriteLine($Line)
|
||||
$logWriter.Flush()
|
||||
}
|
||||
|
||||
try {
|
||||
Write-VerificationLogLine "[Agent Harness] scheduled verification started=$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss zzz')"
|
||||
Write-VerificationLogLine "[Agent Harness] computer=$env:COMPUTERNAME"
|
||||
Write-VerificationLogLine "[Agent Harness] log=$logFile"
|
||||
|
||||
$powershellCommand = Join-Path $PSHOME 'powershell.exe'
|
||||
|
||||
& $powershellCommand `
|
||||
-NoProfile `
|
||||
-NonInteractive `
|
||||
-ExecutionPolicy Bypass `
|
||||
-File $verificationScript `
|
||||
-WorkspaceRoot $resolvedWorkspaceRoot 2>&1 |
|
||||
ForEach-Object {
|
||||
Write-VerificationLogLine $_.ToString()
|
||||
}
|
||||
|
||||
$exitCode = $LASTEXITCODE
|
||||
if ($null -eq $exitCode) {
|
||||
$exitCode = 1
|
||||
}
|
||||
|
||||
Write-VerificationLogLine "[Agent Harness] scheduled verification exitCode=$exitCode"
|
||||
}
|
||||
catch {
|
||||
Write-VerificationLogLine "[Agent Harness] scheduled verification error=$($_.Exception.Message)"
|
||||
$exitCode = 1
|
||||
}
|
||||
finally {
|
||||
$logWriter.Dispose()
|
||||
}
|
||||
|
||||
$retentionCutoff = (Get-Date).AddDays(-$RetentionDays)
|
||||
|
||||
try {
|
||||
Get-ChildItem -LiteralPath $resolvedLogDirectory -File -Filter 'verify-*.log' |
|
||||
Where-Object {
|
||||
$_.FullName -ne $logFile -and $_.LastWriteTime -lt $retentionCutoff
|
||||
} |
|
||||
ForEach-Object {
|
||||
Remove-Item -LiteralPath $_.FullName -Force
|
||||
}
|
||||
}
|
||||
catch {
|
||||
Write-Warning "Failed to remove an expired verification log: $($_.Exception.Message)"
|
||||
}
|
||||
|
||||
exit $exitCode
|
||||
Reference in New Issue
Block a user