claude-dev-env 2.9.0 → 2.10.0

package/scripts/Sync-RepoMain.ps1

@@ -0,0 +1,215 @@
+#Requires -Version 7.0
+<#
+.SYNOPSIS
+  Fast-forward a local main-tracking mirror to its remote main.
+
+.DESCRIPTION
+  Runs against any working tree that is meant to stay on one branch and follow
+  a remote, such as a read-only mirror kept current by a scheduled task.
+
+  Safety rules:
+  - Only runs when the checked-out branch is the named branch
+  - Only runs when there are no tracked changes (untracked files are fine),
+    unless -StashDirty is passed
+  - Uses merge --ff-only only (never force, never hard reset, never clean)
+  - Logs and exits non-zero on skip, diverge, or failure so a Task Scheduler
+    history row can surface a problem instead of a silent no-op
+
+  Exit codes: 0 success, 1 git operation failed, 2 configuration or repo
+  problem, 3 skipped by a safety rule, 4 diverged from the remote.
+
+.PARAMETER RepoPath
+  Absolute path to the git working tree. Required.
+
+.PARAMETER Remote
+  Remote name whose main is the source of truth (default: origin).
+
+.PARAMETER Branch
+  Local branch that must be checked out (default: main).
+
+.PARAMETER StashDirty
+  Changes the tracked-changes branch from skip to stash. With the switch, a
+  tree carrying tracked modifications is stashed with the message
+  "pre-sync stash <yyyy-MM-dd>: uncommitted other-stream edits before ff to
+  <remote>/<branch>" right before the fast-forward, and the stash is left in
+  the stash list for a human to inspect. Untracked files are never stashed.
+  The stash runs only when the fast-forward is going to happen, so an
+  already-up-to-date or diverged run creates no stash entry. If the
+  fast-forward then fails, the stash is popped back so the edits do not go
+  missing; when that pop also fails, the log names the stash entry so the
+  operator can recover it by hand.
+
+.PARAMETER LogPath
+  Absolute path to the run log (default: $HOME\.claude\logs\sync-repo-main.log).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [string]$RepoPath,
+    [string]$Remote = 'origin',
+    [string]$Branch = 'main',
+    [switch]$StashDirty,
+    [string]$LogPath = (Join-Path $HOME '.claude\logs\sync-repo-main.log')
+)
+
+$ErrorActionPreference = 'Stop'
+
+$logDirectory = Split-Path -Parent $LogPath
+if (-not (Test-Path -LiteralPath $logDirectory)) {
+    New-Item -ItemType Directory -Force -Path $logDirectory | Out-Null
+}
+
+function Write-SyncLog {
+    param(
+        [Parameter(Mandatory)]
+        [string]$Level,
+        [Parameter(Mandatory)]
+        [string]$Message
+    )
+    $line = '{0} [{1}] {2}' -f (Get-Date -Format 'o'), $Level, $Message
+    Add-Content -LiteralPath $LogPath -Value $line -Encoding utf8
+    Write-Host $line
+}
+
+function Get-GitExecutable {
+    $command = Get-Command git -ErrorAction SilentlyContinue
+    if ($null -eq $command) {
+        throw 'git executable not found on PATH'
+    }
+    return $command.Source
+}
+
+function Invoke-Git {
+    param(
+        [Parameter(Mandatory)]
+        [string[]]$Arguments
+    )
+    $output = & $script:gitPath -C $RepoPath @Arguments 2>&1
+    $exitCode = $LASTEXITCODE
+    return [pscustomobject]@{
+        ExitCode = $exitCode
+        Output   = ($output | Out-String).Trim()
+    }
+}
+
+function Get-GitDecoration {
+    <#
+      Reads a value used only to decorate a log line. The sync has already
+      succeeded by the time these run, so a failure here returns a placeholder
+      rather than turning a completed sync into a failed run.
+    #>
+    param(
+        [Parameter(Mandatory)]
+        [string[]]$Arguments,
+        [Parameter(Mandatory)]
+        [string]$Placeholder
+    )
+    $result = Invoke-Git -Arguments $Arguments
+    if ($result.ExitCode -ne 0 -or -not $result.Output.Trim()) {
+        return $Placeholder
+    }
+    return $result.Output
+}
+
+function Invoke-GitOrExit {
+    param(
+        [Parameter(Mandatory)]
+        [string[]]$Arguments,
+        [Parameter(Mandatory)]
+        [string]$FailureMessage,
+        [Parameter(Mandatory)]
+        [int]$FailureExitCode
+    )
+    $result = Invoke-Git -Arguments $Arguments
+    if ($result.ExitCode -ne 0) {
+        Write-SyncLog -Level 'ERROR' -Message "${FailureMessage}: $($result.Output)"
+        exit $FailureExitCode
+    }
+    return $result.Output
+}
+
+try {
+    if (-not (Test-Path -LiteralPath $RepoPath)) {
+        Write-SyncLog -Level 'ERROR' -Message "repo path missing: $RepoPath"
+        exit 2
+    }
+
+    $script:gitPath = Get-GitExecutable
+
+    $currentBranch = Invoke-GitOrExit -Arguments @('branch', '--show-current') `
+        -FailureMessage 'cannot read current branch' -FailureExitCode 2
+    if ($currentBranch -ne $Branch) {
+        Write-SyncLog -Level 'SKIP' -Message "checkout is '$currentBranch', not '$Branch' (remote=$Remote)"
+        exit 3
+    }
+
+    $statusOutput = Invoke-GitOrExit -Arguments @('status', '--porcelain') `
+        -FailureMessage 'status failed' -FailureExitCode 2
+    $trackedDirtyLines = @($statusOutput -split "`r?`n" | Where-Object { $_.Trim() -and -not $_.StartsWith('??') })
+    if ($trackedDirtyLines.Count -gt 0 -and -not $StashDirty) {
+        Write-SyncLog -Level 'SKIP' -Message ("tracked changes present; refusing sync: " + ($trackedDirtyLines -join '; '))
+        exit 3
+    }
+
+    $null = Invoke-GitOrExit -Arguments @('fetch', $Remote, $Branch) `
+        -FailureMessage "fetch $Remote $Branch failed" -FailureExitCode 1
+
+    $tipOutput = Invoke-GitOrExit -Arguments @('rev-parse', $Branch, "$Remote/$Branch") `
+        -FailureMessage 'rev-parse of branch tips failed' -FailureExitCode 2
+    $tipLines = @($tipOutput -split "`r?`n" | Where-Object { $_.Trim() })
+    if ($tipLines.Count -ne 2) {
+        Write-SyncLog -Level 'ERROR' -Message "rev-parse returned $($tipLines.Count) tip(s), expected 2: $tipOutput"
+        exit 2
+    }
+    $localTip = $tipLines[0].Trim()
+    $remoteTip = $tipLines[1].Trim()
+
+    if ($localTip -eq $remoteTip) {
+        $remoteUrl = Get-GitDecoration -Arguments @('remote', 'get-url', $Remote) -Placeholder '<url unavailable>'
+        Write-SyncLog -Level 'OK' -Message "already up to date at $localTip ($Remote/$Branch $remoteUrl)"
+        exit 0
+    }
+
+    $ancestorResult = Invoke-Git -Arguments @('merge-base', '--is-ancestor', $Branch, "$Remote/$Branch")
+    if ($ancestorResult.ExitCode -ne 0) {
+        $countResult = Invoke-Git -Arguments @('rev-list', '--left-right', '--count', "${Branch}...${Remote}/${Branch}")
+        Write-SyncLog -Level 'ERROR' -Message "diverged from $Remote/$Branch (counts=$($countResult.Output)); fast-forward refused. local=$localTip remote=$remoteTip"
+        exit 4
+    }
+
+    $didStash = $false
+    if ($trackedDirtyLines.Count -gt 0) {
+        $stashMessage = 'pre-sync stash {0}: uncommitted other-stream edits before ff to {1}/{2}' -f (Get-Date -Format 'yyyy-MM-dd'), $Remote, $Branch
+        $stashResult = Invoke-Git -Arguments @('stash', 'push', '-m', $stashMessage)
+        if ($stashResult.ExitCode -ne 0) {
+            Write-SyncLog -Level 'ERROR' -Message "stash push failed; fast-forward abandoned: $($stashResult.Output)"
+            exit 1
+        }
+        $didStash = $true
+        Write-SyncLog -Level 'STASH' -Message ("stashed tracked changes as '" + $stashMessage + "' (left in stash list): " + ($trackedDirtyLines -join '; '))
+    }
+
+    $mergeResult = Invoke-Git -Arguments @('merge', '--ff-only', "$Remote/$Branch")
+    if ($mergeResult.ExitCode -ne 0) {
+        Write-SyncLog -Level 'ERROR' -Message "merge --ff-only failed: $($mergeResult.Output)"
+        if ($didStash) {
+            $popResult = Invoke-Git -Arguments @('stash', 'pop')
+            if ($popResult.ExitCode -eq 0) {
+                Write-SyncLog -Level 'OK' -Message "restored the stashed edits to the working tree after the failed fast-forward"
+            }
+            else {
+                Write-SyncLog -Level 'ERROR' -Message ("stash pop failed after the failed fast-forward; the edits are still stashed as '" + $stashMessage + "' — recover them with git stash list and git stash pop: " + $popResult.Output)
+            }
+        }
+        exit 1
+    }
+
+    $subject = Get-GitDecoration -Arguments @('log', '-1', '--format=%h %s') -Placeholder '<subject unavailable>'
+    $remoteUrl = Get-GitDecoration -Arguments @('remote', 'get-url', $Remote) -Placeholder '<url unavailable>'
+    Write-SyncLog -Level 'OK' -Message "$Branch $localTip -> $remoteTip | $subject | $Remote/$Branch $remoteUrl"
+    exit 0
+}
+catch {
+    Write-SyncLog -Level 'ERROR' -Message $_.Exception.Message
+    exit 1
+}

package/scripts/active_capability_references.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Resolve active skill, agent, command, and tool references in prompt surfaces.
+
+Builds inventories from committed skill manifests, agent markdown files, and
+commands. Scans active prompt text for slash and backticked capability names.
+Fails when an active (non-inert) reference names a banned capability.
+
+::
+
+    unresolved = unresolved_active_capabilities(package_root)
+    ok: unresolved == []
+    flag: active text mentions /qbug or `stub-detector`
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from dev_env_scripts_constants.active_capability_constants import (
+    ALL_BANNED_ACTIVE_CAPABILITY_NAMES,
+    ALL_INERT_FENCE_LANGUAGES,
+    BACKTICK_CAPABILITY_PATTERN,
+    BANNED_REASON_PREFIX,
+    FENCE_CLOSE_PATTERN,
+    FENCE_OPEN_PATTERN,
+    NEWLINE_JOIN_SEPARATOR,
+    PACKAGE_AGENTS_DIRECTORY,
+    PACKAGE_COMMANDS_DIRECTORY,
+    PACKAGE_SKILLS_DIRECTORY,
+    SKILL_MANIFEST_FILENAME,
+    SLASH_CAPABILITY_PATTERN,
+    UTF8_ENCODING,
+)
+
+
+@dataclass(frozen=True)
+class CapabilityInventory:
+    """Committed capability names by kind."""
+
+    all_skill_names: frozenset[str]
+    all_agent_names: frozenset[str]
+    all_command_names: frozenset[str]
+
+    def all_known_names(self) -> frozenset[str]:
+        """Return the union of skill, agent, and command names."""
+        return self.all_skill_names | self.all_agent_names | self.all_command_names
+
+
+@dataclass(frozen=True)
+class UnresolvedCapabilityReference:
+    """One active reference that names a banned capability."""
+
+    file_path: str
+    line_number: int
+    capability_name: str
+    reason: str
+
+
+def build_capability_inventory(from_package_root: Path) -> CapabilityInventory:
+    """Build inventories from committed skill/agent/command files.
+
+    Args:
+        from_package_root: ``packages/claude-dev-env`` root.
+
+    Returns:
+        Inventory of basenames present on disk.
+    """
+    skills_root = from_package_root / PACKAGE_SKILLS_DIRECTORY
+    agents_root = from_package_root / PACKAGE_AGENTS_DIRECTORY
+    commands_root = from_package_root / PACKAGE_COMMANDS_DIRECTORY
+    all_skills: set[str] = set()
+    if skills_root.is_dir():
+        for each_skill_directory in skills_root.iterdir():
+            if each_skill_directory.is_dir() and (
+                each_skill_directory / SKILL_MANIFEST_FILENAME
+            ).is_file():
+                all_skills.add(each_skill_directory.name)
+    all_agents: set[str] = set()
+    if agents_root.is_dir():
+        for each_agent_file in agents_root.glob("*.md"):
+            all_agents.add(each_agent_file.stem)
+    all_commands: set[str] = set()
+    if commands_root.is_dir():
+        for each_command_file in commands_root.glob("*.md"):
+            all_commands.add(each_command_file.stem)
+    return CapabilityInventory(
+        all_skill_names=frozenset(all_skills),
+        all_agent_names=frozenset(all_agents),
+        all_command_names=frozenset(all_commands),
+    )
+
+
+def strip_inert_fenced_blocks(markdown_text: str) -> str:
+    """Remove fenced blocks tagged as historical/example content.
+
+    Args:
+        markdown_text: Full markdown source.
+
+    Returns:
+        Text with inert fenced blocks replaced by blank lines.
+    """
+    fence_open_pattern = re.compile(FENCE_OPEN_PATTERN)
+    fence_close_pattern = re.compile(FENCE_CLOSE_PATTERN)
+    all_lines = markdown_text.splitlines()
+    all_kept: list[str] = []
+    is_inside_inert = False
+    for each_line in all_lines:
+        open_match = fence_open_pattern.match(each_line)
+        if open_match and not is_inside_inert:
+            language = (open_match.group(1) or "").lower()
+            if language in ALL_INERT_FENCE_LANGUAGES:
+                is_inside_inert = True
+                all_kept.append("")
+                continue
+        if is_inside_inert:
+            if fence_close_pattern.match(each_line):
+                is_inside_inert = False
+            all_kept.append("")
+            continue
+        all_kept.append(each_line)
+    return NEWLINE_JOIN_SEPARATOR.join(all_kept)
+
+
+def extract_active_capability_names(markdown_text: str) -> list[tuple[int, str]]:
+    """Return (1-based line, capability name) for active references.
+
+    Args:
+        markdown_text: Prompt or skill markdown.
+
+    Returns:
+        Ordered list of line number and capability name pairs.
+    """
+    slash_pattern = re.compile(SLASH_CAPABILITY_PATTERN)
+    backtick_pattern = re.compile(BACKTICK_CAPABILITY_PATTERN)
+    active_text = strip_inert_fenced_blocks(markdown_text)
+    all_hits: list[tuple[int, str]] = []
+    for each_line_number, each_line in enumerate(active_text.splitlines(), start=1):
+        for each_match in slash_pattern.finditer(each_line):
+            all_hits.append((each_line_number, each_match.group(1)))
+        for each_match in backtick_pattern.finditer(each_line):
+            all_hits.append((each_line_number, each_match.group(1)))
+    return all_hits
+
+
+def classify_capability_reference(capability_name: str) -> str | None:
+    """Return a failure reason when the capability is banned.
+
+    Extractors also match ordinary prose tokens, so unknown names pass.
+    Only the ban list fails a reference.
+
+    Args:
+        capability_name: Extracted skill/command-like name.
+
+    Returns:
+        Reason string, or None when the reference is allowed.
+    """
+    if capability_name in ALL_BANNED_ACTIVE_CAPABILITY_NAMES:
+        return f"{BANNED_REASON_PREFIX}{capability_name}"
+    return None
+
+
+def unresolved_active_capabilities(
+    from_package_root: Path,
+    *,
+    all_relative_markdown_paths: list[str] | None = None,
+) -> list[UnresolvedCapabilityReference]:
+    """Scan package markdown for banned active capability references.
+
+    Args:
+        from_package_root: ``packages/claude-dev-env`` root.
+        all_relative_markdown_paths: Optional explicit relative paths to scan;
+            defaults to all skills, agents, and commands markdown.
+
+    Returns:
+        Banned references with file, line, name, and reason.
+    """
+    if all_relative_markdown_paths is None:
+        all_relative_markdown_paths = _default_markdown_paths(from_package_root)
+    all_unresolved: list[UnresolvedCapabilityReference] = []
+    for each_relative_path in all_relative_markdown_paths:
+        absolute_path = from_package_root / each_relative_path
+        if not absolute_path.is_file():
+            continue
+        markdown_text = absolute_path.read_text(encoding=UTF8_ENCODING)
+        for each_line_number, each_name in extract_active_capability_names(
+            markdown_text
+        ):
+            reason = classify_capability_reference(each_name)
+            if reason is None:
+                continue
+            all_unresolved.append(
+                UnresolvedCapabilityReference(
+                    file_path=each_relative_path.replace("\\", "/"),
+                    line_number=each_line_number,
+                    capability_name=each_name,
+                    reason=reason,
+                )
+            )
+    return all_unresolved
+
+
+def _default_markdown_paths(from_package_root: Path) -> list[str]:
+    all_paths: list[str] = []
+    for each_directory_name in (
+        PACKAGE_SKILLS_DIRECTORY,
+        PACKAGE_AGENTS_DIRECTORY,
+        PACKAGE_COMMANDS_DIRECTORY,
+    ):
+        directory_path = from_package_root / each_directory_name
+        if not directory_path.is_dir():
+            continue
+        for each_markdown_file in directory_path.rglob("*.md"):
+            all_paths.append(
+                each_markdown_file.relative_to(from_package_root).as_posix()
+            )
+    return all_paths

package/scripts/ci/windows-installer-lifecycle.ps1

@@ -0,0 +1,78 @@
+# Windows CI adapter for the Node installer lifecycle driver.
+#
+# The driver already redirects HOME, USERPROFILE, and GIT_CONFIG_GLOBAL into a
+# throwaway sandbox. This adapter records that isolation contract, runs the
+# 16-check driver, and writes bounded evidence under -EvidenceRoot so a failed
+# Windows runner leaves an actionable artifact.
+#
+# Usage (from packages/claude-dev-env):
+#   pwsh -NoProfile -File scripts/ci/windows-installer-lifecycle.ps1 -EvidenceRoot <dir>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$EvidenceRoot
+)
+
+$ErrorActionPreference = 'Stop'
+
+$packageRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+$driverPath = Join-Path $packageRoot '.claude\skills\run-claude-dev-env\driver.mjs'
+$allIsolationEnvNames = @(
+    'HOME',
+    'USERPROFILE',
+    'GIT_CONFIG_GLOBAL'
+)
+
+if (-not (Test-Path -LiteralPath $driverPath)) {
+    throw "Lifecycle driver missing at $driverPath"
+}
+
+New-Item -ItemType Directory -Force -Path $EvidenceRoot | Out-Null
+
+$preflightPath = Join-Path $EvidenceRoot 'preflight.json'
+$driverLogPath = Join-Path $EvidenceRoot 'driver.log'
+$summaryPath = Join-Path $EvidenceRoot 'summary.json'
+
+$preflight = [ordered]@{
+    packageRoot = $packageRoot
+    driverPath = $driverPath
+    platform = [System.Environment]::OSVersion.VersionString
+    nodeVersion = (& node --version 2>&1 | Out-String).Trim()
+    pythonVersion = (& python --version 2>&1 | Out-String).Trim()
+    isolationContract = $allIsolationEnvNames
+    note = 'Driver owns isolation roots; adapter never points at the real user profile.'
+}
+$preflight | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $preflightPath -Encoding utf8
+
+Write-Host "Evidence root: $EvidenceRoot"
+Write-Host "Driver: $driverPath"
+Write-Host ("Isolation contract: {0} (driver-owned sandbox)" -f ($allIsolationEnvNames -join ', '))
+
+$driverOutput = & node $driverPath 2>&1
+$driverExitCode = $LASTEXITCODE
+$driverOutput | ForEach-Object { Write-Host $_ }
+$driverOutputText = ($driverOutput | Out-String)
+[System.IO.File]::WriteAllText($driverLogPath, $driverOutputText)
+
+$passedCheckMatch = [regex]::Match($driverOutputText, '(\d+)/(\d+) checks passed')
+$summary = [ordered]@{
+    exitCode = $driverExitCode
+    allChecksPassed = ($driverExitCode -eq 0 -and $driverOutputText -match 'ALL CHECKS PASSED')
+    checksLine = if ($passedCheckMatch.Success) { $passedCheckMatch.Value } else { 'unparsed' }
+    evidenceFiles = @(
+        'preflight.json',
+        'driver.log',
+        'summary.json'
+    )
+}
+$summary | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $summaryPath -Encoding utf8
+
+if ($driverExitCode -ne 0) {
+    throw "Lifecycle driver exited $driverExitCode (see $driverLogPath)"
+}
+if ($driverOutputText -notmatch 'ALL CHECKS PASSED') {
+    throw "Lifecycle driver output missing ALL CHECKS PASSED (see $driverLogPath)"
+}
+
+Write-Host "Windows installer lifecycle: OK"