From 76ded1947d241520917199af8f270026410b1e2a Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Mon, 10 Aug 2026 14:10:25 +0900 Subject: [PATCH] feat: schedule local workspace verification --- .gitignore | 1 + Jenkinsfile | 52 ---------- README.md | 17 +++- docs/jenkins.md | 56 ----------- docs/local-scheduling.md | 54 +++++++++++ package.json | 5 +- scripts/register-scheduled-verification.ps1 | 100 ++++++++++++++++++++ scripts/run-scheduled-verification.ps1 | 89 +++++++++++++++++ 8 files changed, 264 insertions(+), 110 deletions(-) delete mode 100644 Jenkinsfile delete mode 100644 docs/jenkins.md create mode 100644 docs/local-scheduling.md create mode 100644 scripts/register-scheduled-verification.ps1 create mode 100644 scripts/run-scheduled-verification.ps1 diff --git a/.gitignore b/.gitignore index 96070c3..93fad81 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /node_modules/ /.build/ /workspace.local.yml +/.local/ *.tmp *.bak diff --git a/Jenkinsfile b/Jenkinsfile deleted file mode 100644 index 78379dc..0000000 --- a/Jenkinsfile +++ /dev/null @@ -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.' - } - } -} diff --git a/README.md b/README.md index fea7984..0080994 100644 --- a/README.md +++ b/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. diff --git a/docs/jenkins.md b/docs/jenkins.md deleted file mode 100644 index 8c3e1cd..0000000 --- a/docs/jenkins.md +++ /dev/null @@ -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 -``` - -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. diff --git a/docs/local-scheduling.md b/docs/local-scheduling.md new file mode 100644 index 0000000..ac06428 --- /dev/null +++ b/docs/local-scheduling.md @@ -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 +``` + +## 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. diff --git a/package.json b/package.json index ac86035..67f515c 100644 --- a/package.json +++ b/package.json @@ -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" diff --git a/scripts/register-scheduled-verification.ps1 b/scripts/register-scheduled-verification.ps1 new file mode 100644 index 0000000..38a6c81 --- /dev/null +++ b/scripts/register-scheduled-verification.ps1 @@ -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" diff --git a/scripts/run-scheduled-verification.ps1 b/scripts/run-scheduled-verification.ps1 new file mode 100644 index 0000000..3d18c79 --- /dev/null +++ b/scripts/run-scheduled-verification.ps1 @@ -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