@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/sync-project-root-docs/scripts/collect-root-doc-facts.ps1

@@ -1,145 +1,174 @@
-param(
-  [string]$ProjectRoot = "."
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = "Stop"
-
-function Read-Text {
-  param([string]$Path)
-
-  if (-not (Test-Path -LiteralPath $Path)) {
-    return $null
-  }
-
-  return Get-Content -LiteralPath $Path -Raw
-}
-
-function Read-Json {
-  param([string]$Path)
-
-  $text = Read-Text -Path $Path
-  if ([string]::IsNullOrWhiteSpace($text)) {
-    return $null
-  }
-
-  try {
-    return $text | ConvertFrom-Json
-  }
-  catch {
-    return $null
-  }
-}
-
-function Get-RelativeNames {
-  param([string]$DirectoryPath)
-
-  if (-not (Test-Path -LiteralPath $DirectoryPath)) {
-    return @()
-  }
-
-  return @(
-    Get-ChildItem -LiteralPath $DirectoryPath -File |
-      Sort-Object Name |
-      Select-Object -ExpandProperty Name
-  )
-}
-
-$root = (Resolve-Path -LiteralPath $ProjectRoot).Path
-$readmePath = Join-Path $root "README.md"
-$agentsPath = Join-Path $root "AGENTS.md"
-$bootstrapPath = Join-Path $root "tools/install/bootstrap-codex-harness.ps1"
-$taskPath = Join-Path $root "task.json"
-$templateTaskPath = Join-Path $root "tools/harness/templates/project-task-template.json"
-$profilePath = Join-Path $root ".codex\task-run-profile.json"
-
-$readmeText = Read-Text -Path $readmePath
-$bootstrapText = Read-Text -Path $bootstrapPath
-$taskJson = Read-Json -Path $taskPath
-$templateTaskJson = Read-Json -Path $templateTaskPath
-$profileJson = Read-Json -Path $profilePath
-
-$placeholderReadme = $false
-if (-not [string]::IsNullOrWhiteSpace($readmeText)) {
-  $placeholderReadme = $readmeText -match "generated by install-agent\.ps1" -or
-    $readmeText -match "Replace it with project-specific content"
-}
-
-$managedDestinations = @()
-if (-not [string]::IsNullOrWhiteSpace($bootstrapText)) {
-  $managedDestinations = @(
-    [regex]::Matches($bootstrapText, 'Destination = "([^"]+)"') |
-      ForEach-Object { $_.Groups[1].Value } |
-      Sort-Object -Unique
-  )
-}
-
-$rootItems = @(
-  Get-ChildItem -LiteralPath $root -Force |
-    Sort-Object Name |
-    Select-Object -ExpandProperty Name
-)
-
-$harnessDocs = Get-RelativeNames -DirectoryPath (Join-Path $root "docs\harness")
-$testingDocs = Get-RelativeNames -DirectoryPath (Join-Path $root "docs\testing")
-
-Write-Output "# Root Doc Facts"
-Write-Output ""
-Write-Output ("- Generated: {0}" -f (Get-Date -Format "yyyy-MM-dd HH:mm:ss"))
-Write-Output ('- Project root: `{0}`' -f $root)
-Write-Output ("- Placeholder README detected: {0}" -f ($(if ($placeholderReadme) { "yes" } else { "no" })))
-Write-Output ('- Active capability surface `.agents/`: {0}' -f ($(if (Test-Path -LiteralPath (Join-Path $root ".agents")) { "present" } else { "missing" })))
-Write-Output ('- Distributable package surface `agent/`: {0}' -f ($(if (Test-Path -LiteralPath (Join-Path $root "agent")) { "present" } else { "missing" })))
-Write-Output ""
-Write-Output "## Root Items"
-foreach ($item in $rootItems) {
-  Write-Output ('- `{0}`' -f $item)
-}
-
-Write-Output ""
-Write-Output "## Runtime Signals"
-Write-Output ('- Root `AGENTS.md` exists: {0}' -f ($(if (Test-Path -LiteralPath $agentsPath) { "yes" } else { "no" })))
-Write-Output ('- Root `README.md` exists: {0}' -f ($(if (Test-Path -LiteralPath $readmePath) { "yes" } else { "no" })))
-Write-Output ('- `task.json` first task: {0}' -f $(if ($taskJson -and $taskJson.tasks -and $taskJson.tasks.Count -gt 0) { $taskJson.tasks[0].id } else { "n/a" }))
-Write-Output ('- `task.json` runtime.driver: {0}' -f $(if ($taskJson -and $taskJson.runtime -and $taskJson.runtime.driver) { $taskJson.runtime.driver } else { "n/a" }))
-Write-Output ('- `tools/harness/templates/project-task-template.json` first task: {0}' -f $(if ($templateTaskJson -and $templateTaskJson.tasks -and $templateTaskJson.tasks.Count -gt 0) { $templateTaskJson.tasks[0].id } else { "n/a" }))
-Write-Output ('- `.codex/task-run-profile.json` session mode: {0}' -f $(if ($profileJson -and $profileJson.session -and $profileJson.session.mode) { $profileJson.session.mode } else { "n/a" }))
-
-if ($profileJson -and $profileJson.session -and $profileJson.session.context_sources) {
-  Write-Output '- `.codex/task-run-profile.json` context sources:'
-  foreach ($source in $profileJson.session.context_sources) {
-    Write-Output ('  - `{0}`' -f $source)
-  }
-}
-
-if ($profileJson -and $profileJson.subagents -and $profileJson.subagents.allowed_roles) {
-  Write-Output ("- Allowed subagent roles: {0}" -f ($profileJson.subagents.allowed_roles -join ", "))
-}
-
-Write-Output ""
-Write-Output "## Docs"
-Write-Output ('- `docs/harness/*`: {0}' -f $(if ($harnessDocs.Count -gt 0) { $harnessDocs -join ", " } else { "none" }))
-Write-Output ('- `docs/testing/*`: {0}' -f $(if ($testingDocs.Count -gt 0) { $testingDocs -join ", " } else { "none" }))
-
-Write-Output ""
-Write-Output "## tools/install/bootstrap-codex-harness.ps1 Destinations"
-if ($managedDestinations.Count -eq 0) {
-  Write-Output "- none detected"
-}
-else {
-  foreach ($destination in $managedDestinations) {
-    Write-Output ('- `{0}`' -f $destination)
-  }
-}
-
-Write-Output ""
-Write-Output "## Suggested Angle"
-if ($placeholderReadme -and (Test-Path -LiteralPath (Join-Path $root "agent")) -and (Test-Path -LiteralPath (Join-Path $root ".agents"))) {
-  Write-Output '- Treat the repo as a runtime-plus-package repository and explain `.agents/` vs `agent/` clearly.'
-}
-elseif ($placeholderReadme) {
-  Write-Output "- Replace the placeholder README with a project-specific entrypoint derived from scripts and docs."
-}
-else {
-  Write-Output "- Compare the current root docs against runtime scripts and deep docs before rewriting anything."
-}
+param(
+  [string]$ProjectRoot = "."
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Read-Text {
+  param([string]$Path)
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  return Get-Content -LiteralPath $Path -Raw
+}
+
+function Read-Json {
+  param([string]$Path)
+
+  $text = Read-Text -Path $Path
+  if ([string]::IsNullOrWhiteSpace($text)) {
+    return $null
+  }
+
+  try {
+    return $text | ConvertFrom-Json
+  }
+  catch {
+    return $null
+  }
+}
+
+function Get-HarnessPackageRoot {
+  param([string]$Root)
+
+  $configPath = Join-Path $Root ".codex-harness\state\config.json"
+  $config = Read-Json -Path $configPath
+  if ($null -eq $config) {
+    return ""
+  }
+
+  $packageRoot = [string]$config.packageRoot
+  if ([string]::IsNullOrWhiteSpace($packageRoot)) {
+    return ""
+  }
+
+  return [System.IO.Path]::GetFullPath($packageRoot)
+}
+
+function Get-RelativeNames {
+  param([string]$DirectoryPath)
+
+  if (-not (Test-Path -LiteralPath $DirectoryPath)) {
+    return @()
+  }
+
+  return @(
+    Get-ChildItem -LiteralPath $DirectoryPath -File |
+      Sort-Object Name |
+      Select-Object -ExpandProperty Name
+  )
+}
+
+$root = (Resolve-Path -LiteralPath $ProjectRoot).Path
+$readmePath = Join-Path $root "README.md"
+$agentsPath = Join-Path $root "AGENTS.md"
+$bootstrapPath = Join-Path $root "tools/install/bootstrap-codex-harness.ps1"
+$taskPath = Join-Path $root "task.json"
+$templateTaskPath = Join-Path $root "tools/harness/templates/project-task-template.json"
+$profilePath = Join-Path $root ".codex\task-run-profile.json"
+
+$readmeText = Read-Text -Path $readmePath
+$bootstrapText = Read-Text -Path $bootstrapPath
+$taskJson = Read-Json -Path $taskPath
+$templateTaskJson = Read-Json -Path $templateTaskPath
+$profileJson = Read-Json -Path $profilePath
+$packageRoot = Get-HarnessPackageRoot -Root $root
+
+$placeholderReadme = $false
+if (-not [string]::IsNullOrWhiteSpace($readmeText)) {
+  $placeholderReadme = $readmeText -match "generated by install-agent\.ps1" -or
+    $readmeText -match "Replace it with project-specific content"
+}
+
+$managedDestinations = @()
+if (-not [string]::IsNullOrWhiteSpace($bootstrapText)) {
+  $managedDestinations = @(
+    [regex]::Matches($bootstrapText, 'Destination = "([^"]+)"') |
+      ForEach-Object { $_.Groups[1].Value } |
+      Sort-Object -Unique
+  )
+}
+
+$rootItems = @(
+  Get-ChildItem -LiteralPath $root -Force |
+    Sort-Object Name |
+    Select-Object -ExpandProperty Name
+)
+
+$harnessDocs = Get-RelativeNames -DirectoryPath (Join-Path $root "docs\harness")
+$testingDocs = Get-RelativeNames -DirectoryPath (Join-Path $root "docs\testing")
+$packageHarnessDocs = @()
+$packageTestingDocs = @()
+if (-not [string]::IsNullOrWhiteSpace($packageRoot)) {
+  $packageHarnessDocs = Get-RelativeNames -DirectoryPath (Join-Path $packageRoot "docs\harness")
+  $packageTestingDocs = Get-RelativeNames -DirectoryPath (Join-Path $packageRoot "docs\testing")
+}
+
+Write-Output "# Root Doc Facts"
+Write-Output ""
+Write-Output ("- Generated: {0}" -f (Get-Date -Format "yyyy-MM-dd HH:mm:ss"))
+Write-Output ('- Project root: `{0}`' -f $root)
+Write-Output ("- Placeholder README detected: {0}" -f ($(if ($placeholderReadme) { "yes" } else { "no" })))
+Write-Output ('- Active capability surface `.agents/`: {0}' -f ($(if (Test-Path -LiteralPath (Join-Path $root ".agents")) { "present" } else { "missing" })))
+Write-Output ('- Distributable package surface `agent/`: {0}' -f ($(if (Test-Path -LiteralPath (Join-Path $root "agent")) { "present" } else { "missing" })))
+Write-Output ""
+Write-Output "## Root Items"
+foreach ($item in $rootItems) {
+  Write-Output ('- `{0}`' -f $item)
+}
+
+Write-Output ""
+Write-Output "## Runtime Signals"
+Write-Output ('- Root `AGENTS.md` exists: {0}' -f ($(if (Test-Path -LiteralPath $agentsPath) { "yes" } else { "no" })))
+Write-Output ('- Root `README.md` exists: {0}' -f ($(if (Test-Path -LiteralPath $readmePath) { "yes" } else { "no" })))
+Write-Output ('- `task.json` first task: {0}' -f $(if ($taskJson -and $taskJson.tasks -and $taskJson.tasks.Count -gt 0) { $taskJson.tasks[0].id } else { "n/a" }))
+Write-Output ('- `task.json` runtime.driver: {0}' -f $(if ($taskJson -and $taskJson.runtime -and $taskJson.runtime.driver) { $taskJson.runtime.driver } else { "n/a" }))
+Write-Output ('- `tools/harness/templates/project-task-template.json` first task: {0}' -f $(if ($templateTaskJson -and $templateTaskJson.tasks -and $templateTaskJson.tasks.Count -gt 0) { $templateTaskJson.tasks[0].id } else { "n/a" }))
+Write-Output ('- `.codex/task-run-profile.json` session mode: {0}' -f $(if ($profileJson -and $profileJson.session -and $profileJson.session.mode) { $profileJson.session.mode } else { "n/a" }))
+Write-Output ('- `.codex-harness/state/config.json` packageRoot: {0}' -f $(if ([string]::IsNullOrWhiteSpace($packageRoot)) { "n/a" } else { $packageRoot }))
+
+if ($profileJson -and $profileJson.session -and $profileJson.session.context_sources) {
+  Write-Output '- `.codex/task-run-profile.json` context sources:'
+  foreach ($source in $profileJson.session.context_sources) {
+    Write-Output ('  - `{0}`' -f $source)
+  }
+}
+
+if ($profileJson -and $profileJson.subagents -and $profileJson.subagents.allowed_roles) {
+  Write-Output ("- Allowed subagent roles: {0}" -f ($profileJson.subagents.allowed_roles -join ", "))
+}
+
+Write-Output ""
+Write-Output "## Docs"
+Write-Output ('- `docs/harness/*`: {0}' -f $(if ($harnessDocs.Count -gt 0) { $harnessDocs -join ", " } else { "none" }))
+Write-Output ('- `docs/testing/*`: {0}' -f $(if ($testingDocs.Count -gt 0) { $testingDocs -join ", " } else { "none" }))
+if (($harnessDocs.Count -eq 0 -or $testingDocs.Count -eq 0) -and -not [string]::IsNullOrWhiteSpace($packageRoot)) {
+  Write-Output ('- packageRoot `docs/harness/*`: {0}' -f $(if ($packageHarnessDocs.Count -gt 0) { $packageHarnessDocs -join ", " } else { "none" }))
+  Write-Output ('- packageRoot `docs/testing/*`: {0}' -f $(if ($packageTestingDocs.Count -gt 0) { $packageTestingDocs -join ", " } else { "none" }))
+}
+
+Write-Output ""
+Write-Output "## tools/install/bootstrap-codex-harness.ps1 Destinations"
+if ($managedDestinations.Count -eq 0) {
+  Write-Output "- none detected"
+}
+else {
+  foreach ($destination in $managedDestinations) {
+    Write-Output ('- `{0}`' -f $destination)
+  }
+}
+
+Write-Output ""
+Write-Output "## Suggested Angle"
+if ($placeholderReadme -and (Test-Path -LiteralPath (Join-Path $root "agent")) -and (Test-Path -LiteralPath (Join-Path $root ".agents"))) {
+  Write-Output '- Treat the repo as a runtime-plus-package repository and explain `.agents/` vs `agent/` clearly.'
+}
+elseif ($placeholderReadme) {
+  Write-Output "- Replace the placeholder README with a project-specific entrypoint derived from scripts and docs."
+}
+else {
+  Write-Output "- Compare the current root docs against runtime scripts and deep docs before rewriting anything."
+}