claude-dev-env 2.8.0 → 2.10.0

package/scripts/profile-isolation-launchers/version-compatibility.mjs

@@ -0,0 +1,299 @@
+/**
+ * Pure CLI vs Desktop embedded-version compatibility classifier.
+ *
+ * The classifier takes probe results only. Callers own process spawn, timeouts,
+ * and binary discovery. Fail closed on unreadable or missing inputs.
+ */
+
+export const COMPATIBILITY_POLICY_VERSION = 1;
+
+/** @typedef {'pass' | 'warn' | 'block'} CompatibilityAction */
+/** @typedef {
+ *   | 'equal'
+ *   | 'patch-drift'
+ *   | 'minor-drift'
+ *   | 'major-drift'
+ *   | 'missing-binary'
+ *   | 'unreadable'
+ *   | 'process-error'
+ *   | 'non-semver'
+ * } CompatibilityClass */
+
+/**
+ * Action table for every compatibility class. Missing / unreadable / process
+ * errors and major/minor drift block; patch drift warns; equality passes.
+ */
+export const COMPATIBILITY_ACTION_BY_CLASS = Object.freeze({
+    equal: 'pass',
+    'patch-drift': 'warn',
+    'minor-drift': 'block',
+    'major-drift': 'block',
+    'missing-binary': 'block',
+    unreadable: 'block',
+    'process-error': 'block',
+    'non-semver': 'block',
+});
+
+/**
+ * @typedef {{
+ *   path: string | null,
+ *   versionText: string | null,
+ *   errorCode?: 'missing' | 'unreadable' | 'process-error' | null,
+ *   errorMessage?: string | null,
+ * }} VersionProbeResult
+ */
+
+/**
+ * @typedef {{
+ *   cliPath: string | null,
+ *   desktopPath: string | null,
+ *   cliVersion: string | null,
+ *   desktopVersion: string | null,
+ *   policyVersion: number,
+ *   class: CompatibilityClass,
+ *   action: CompatibilityAction,
+ *   message: string,
+ * }} CompatibilityResult
+ */
+
+/**
+ * Classify CLI and Desktop embedded version compatibility from probe results.
+ *
+ * ::
+ *
+ *     classifyVersionCompatibility({
+ *       cli: { path: 'cli', versionText: '2.1.220' },
+ *       desktop: { path: 'desktop', versionText: '2.1.220' },
+ *     })
+ *     // class: equal, action: pass
+ *
+ *     classifyVersionCompatibility({
+ *       cli: { path: 'cli', versionText: '2.1.220' },
+ *       desktop: { path: 'desktop', versionText: '2.1.219' },
+ *     })
+ *     // class: patch-drift, action: warn
+ *
+ * @param {{
+ *   cli: VersionProbeResult,
+ *   desktop: VersionProbeResult,
+ * }} parameters
+ * @returns {CompatibilityResult}
+ */
+export function classifyVersionCompatibility(parameters) {
+    const cliProbe = normalizeProbe(parameters.cli);
+    const desktopProbe = normalizeProbe(parameters.desktop);
+
+    const base = {
+        cliPath: cliProbe.path,
+        desktopPath: desktopProbe.path,
+        cliVersion: extractVersionLabel(cliProbe.versionText),
+        desktopVersion: extractVersionLabel(desktopProbe.versionText),
+        policyVersion: COMPATIBILITY_POLICY_VERSION,
+    };
+
+    const probeFailure = firstProbeFailure(cliProbe, desktopProbe);
+    if (probeFailure) {
+        return finalizeResult({
+            ...base,
+            class: probeFailure.className,
+            message: probeFailure.message,
+        });
+    }
+
+    const cliVersion = parseSemver(cliProbe.versionText);
+    const desktopVersion = parseSemver(desktopProbe.versionText);
+    if (!cliVersion || !desktopVersion) {
+        return finalizeResult({
+            ...base,
+            class: 'non-semver',
+            message: formatNonSemverMessage(cliProbe.versionText, desktopProbe.versionText),
+        });
+    }
+
+    if (
+        cliVersion.major === desktopVersion.major
+        && cliVersion.minor === desktopVersion.minor
+        && cliVersion.patch === desktopVersion.patch
+    ) {
+        return finalizeResult({
+            ...base,
+            class: 'equal',
+            message: `CLI and Desktop versions match (${formatSemver(cliVersion)})`,
+        });
+    }
+
+    if (cliVersion.major !== desktopVersion.major) {
+        return finalizeResult({
+            ...base,
+            class: 'major-drift',
+            message: formatDriftMessage('major', cliVersion, desktopVersion),
+        });
+    }
+
+    if (cliVersion.minor !== desktopVersion.minor) {
+        return finalizeResult({
+            ...base,
+            class: 'minor-drift',
+            message: formatDriftMessage('minor', cliVersion, desktopVersion),
+        });
+    }
+
+    return finalizeResult({
+        ...base,
+        class: 'patch-drift',
+        message: formatDriftMessage('patch', cliVersion, desktopVersion),
+    });
+}
+
+/**
+ * True when the classified action blocks launch before profile-state mutation.
+ *
+ * @param {CompatibilityResult} result
+ * @returns {boolean}
+ */
+export function shouldBlockLaunch(result) {
+    return result.action === 'block';
+}
+
+/**
+ * Parse a version string into major.minor.patch when the leading triple is semver-shaped.
+ *
+ * @param {string | null | undefined} versionText
+ * @returns {{major: number, minor: number, patch: number} | null}
+ */
+export function parseSemver(versionText) {
+    if (typeof versionText !== 'string') {
+        return null;
+    }
+    const trimmed = versionText.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const match = trimmed.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+        return null;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+
+/**
+ * @param {VersionProbeResult | null | undefined} probe
+ * @returns {VersionProbeResult}
+ */
+function normalizeProbe(probe) {
+    if (!probe || typeof probe !== 'object') {
+        return {
+            path: null,
+            versionText: null,
+            errorCode: 'missing',
+            errorMessage: 'probe missing',
+        };
+    }
+    return {
+        path: typeof probe.path === 'string' ? probe.path : null,
+        versionText: typeof probe.versionText === 'string' ? probe.versionText : null,
+        errorCode: probe.errorCode ?? null,
+        errorMessage: probe.errorMessage ?? null,
+    };
+}
+
+/**
+ * @param {VersionProbeResult} cliProbe
+ * @param {VersionProbeResult} desktopProbe
+ * @returns {{className: CompatibilityClass, message: string} | null}
+ */
+function firstProbeFailure(cliProbe, desktopProbe) {
+    for (const [eachLabel, eachProbe] of [
+        ['CLI', cliProbe],
+        ['Desktop', desktopProbe],
+    ]) {
+        if (eachProbe.errorCode === 'missing' || !eachProbe.path) {
+            return {
+                className: 'missing-binary',
+                message: `${eachLabel} binary path is missing`,
+            };
+        }
+        if (eachProbe.errorCode === 'process-error') {
+            return {
+                className: 'process-error',
+                message: `${eachLabel} version probe failed: ${eachProbe.errorMessage || 'process error'}`,
+            };
+        }
+        if (eachProbe.errorCode === 'unreadable' || eachProbe.versionText === null) {
+            return {
+                className: 'unreadable',
+                message: `${eachLabel} version output is unreadable`,
+            };
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string | null} versionText
+ * @returns {string | null}
+ */
+function extractVersionLabel(versionText) {
+    if (typeof versionText !== 'string') {
+        return null;
+    }
+    const trimmed = versionText.trim();
+    return trimmed || null;
+}
+
+/**
+ * @param {{
+ *   cliPath: string | null,
+ *   desktopPath: string | null,
+ *   cliVersion: string | null,
+ *   desktopVersion: string | null,
+ *   policyVersion: number,
+ *   class: CompatibilityClass,
+ *   message: string,
+ * }} partial
+ * @returns {CompatibilityResult}
+ */
+function finalizeResult(partial) {
+    const action = COMPATIBILITY_ACTION_BY_CLASS[partial.class];
+    return {
+        cliPath: partial.cliPath,
+        desktopPath: partial.desktopPath,
+        cliVersion: partial.cliVersion,
+        desktopVersion: partial.desktopVersion,
+        policyVersion: partial.policyVersion,
+        class: partial.class,
+        action,
+        message: partial.message,
+    };
+}
+
+/**
+ * @param {'major' | 'minor' | 'patch'} axis
+ * @param {{major: number, minor: number, patch: number}} cliVersion
+ * @param {{major: number, minor: number, patch: number}} desktopVersion
+ * @returns {string}
+ */
+function formatDriftMessage(axis, cliVersion, desktopVersion) {
+    return `${axis} drift: CLI ${formatSemver(cliVersion)} vs Desktop ${formatSemver(desktopVersion)}`;
+}
+
+/**
+ * @param {{major: number, minor: number, patch: number}} version
+ * @returns {string}
+ */
+function formatSemver(version) {
+    return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+/**
+ * @param {string | null} cliText
+ * @param {string | null} desktopText
+ * @returns {string}
+ */
+function formatNonSemverMessage(cliText, desktopText) {
+    return `non-semver version text: CLI=${JSON.stringify(cliText)} Desktop=${JSON.stringify(desktopText)}`;
+}

package/scripts/profile-isolation-launchers/windows/shortcut-inventory.ps1

@@ -0,0 +1,127 @@
+# Read-only inventory of managed Claude profile shortcuts.
+# Does not mutate Desktop, Start Menu, or taskbar state.
+
+[CmdletBinding()]
+param(
+    [string]$ManifestPath = (Join-Path $PSScriptRoot 'shortcut-manifest.json'),
+    [string]$DesktopPath = [Environment]::GetFolderPath('Desktop'),
+    [string]$StartMenuPath = [Environment]::GetFolderPath('StartMenu'),
+    [string]$OutputPath
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not (Test-Path -LiteralPath $ManifestPath)) {
+    throw "shortcut manifest missing: $ManifestPath"
+}
+
+$manifest = Get-Content -LiteralPath $ManifestPath -Raw | ConvertFrom-Json
+if ($manifest.schemaVersion -ne 1) {
+    throw "unsupported shortcut manifest schemaVersion: $($manifest.schemaVersion)"
+}
+if ($null -eq $manifest.allManagedShortcuts) {
+    throw 'shortcut manifest allManagedShortcuts is required'
+}
+
+$allSeenIds = @{}
+$allSeenVisibleNames = @{}
+$allSeenGrouping = @{}
+foreach ($eachShortcut in $manifest.allManagedShortcuts) {
+    foreach ($eachFieldName in @('id', 'visibleName', 'source', 'profileId', 'locationKind', 'groupingIdentity')) {
+        $fieldValue = $eachShortcut.$eachFieldName
+        if ([string]::IsNullOrWhiteSpace([string]$fieldValue)) {
+            throw "shortcut missing required field $eachFieldName"
+        }
+    }
+    if ($allSeenIds.ContainsKey($eachShortcut.id)) {
+        throw "duplicate shortcut id: $($eachShortcut.id)"
+    }
+    if ($allSeenVisibleNames.ContainsKey($eachShortcut.visibleName)) {
+        throw "duplicate shortcut visibleName: $($eachShortcut.visibleName)"
+    }
+    if ($allSeenGrouping.ContainsKey($eachShortcut.groupingIdentity)) {
+        throw "duplicate shortcut groupingIdentity: $($eachShortcut.groupingIdentity)"
+    }
+    $allSeenIds[$eachShortcut.id] = $true
+    $allSeenVisibleNames[$eachShortcut.visibleName] = $true
+    $allSeenGrouping[$eachShortcut.groupingIdentity] = $true
+}
+
+function Get-ShortcutMetadata {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ShortcutPath,
+        [Parameter(Mandatory = $true)]
+        $Shell
+    )
+    if (-not (Test-Path -LiteralPath $ShortcutPath)) {
+        return $null
+    }
+    $link = $Shell.CreateShortcut($ShortcutPath)
+    return [pscustomobject]@{
+        path              = $ShortcutPath
+        targetPath        = $link.TargetPath
+        arguments         = $link.Arguments
+        workingDirectory  = $link.WorkingDirectory
+        iconLocation      = $link.IconLocation
+        exists            = $true
+    }
+}
+
+$shell = New-Object -ComObject WScript.Shell
+$allRows = [System.Collections.Generic.List[object]]::new()
+try {
+    foreach ($eachShortcut in $manifest.allManagedShortcuts) {
+        if ($eachShortcut.locationKind -eq 'desktop') {
+            $baseDirectory = $DesktopPath
+        }
+        elseif ($eachShortcut.locationKind -eq 'start-menu') {
+            $baseDirectory = $StartMenuPath
+        }
+        else {
+            throw "unsupported locationKind for $($eachShortcut.id): $($eachShortcut.locationKind)"
+        }
+        $shortcutPath = Join-Path $baseDirectory ($eachShortcut.visibleName + '.lnk')
+        $metadata = Get-ShortcutMetadata -ShortcutPath $shortcutPath -Shell $shell
+        $allRows.Add([pscustomobject]@{
+            id                = $eachShortcut.id
+            visibleName       = $eachShortcut.visibleName
+            source            = $eachShortcut.source
+            profileId         = $eachShortcut.profileId
+            locationKind      = $eachShortcut.locationKind
+            targetKind        = $eachShortcut.targetKind
+            launcherName      = $eachShortcut.launcherName
+            groupingIdentity  = $eachShortcut.groupingIdentity
+            expectedPath      = $shortcutPath
+            exists            = [bool]$metadata
+            targetPath        = if ($metadata) { $metadata.targetPath } else { $null }
+            arguments         = if ($metadata) { $metadata.arguments } else { $null }
+            workingDirectory  = if ($metadata) { $metadata.workingDirectory } else { $null }
+            iconLocation      = if ($metadata) { $metadata.iconLocation } else { $null }
+            liveMutationAuthorized = [bool]$manifest.policy.liveMutationAuthorized
+        })
+    }
+}
+finally {
+    [void][System.Runtime.InteropServices.Marshal]::ReleaseComObject($shell)
+}
+
+$result = [pscustomobject]@{
+    mode = 'read-only-inventory'
+    policy = $manifest.policy
+    scannedAt = (Get-Date).ToString('o')
+    desktopPath = $DesktopPath
+    startMenuPath = $StartMenuPath
+    shortcuts = $allRows
+}
+
+$json = $result | ConvertTo-Json -Depth 6
+if ($OutputPath) {
+    $directory = Split-Path -Parent $OutputPath
+    if ($directory -and -not (Test-Path -LiteralPath $directory)) {
+        New-Item -ItemType Directory -Path $directory | Out-Null
+    }
+    [IO.File]::WriteAllText($OutputPath, $json, [Text.UTF8Encoding]::new($false))
+}
+Write-Output $json

package/scripts/profile-isolation-launchers/windows/shortcut-manifest.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 1,
+  "policy": {
+    "unsuffixedNames": "Native Desktop wins: Claude Profile A and Claude Profile B",
+    "browserNames": "Chrome variants use explicit Web or Chrome source labels",
+    "authority": "The owner confirms or revises this policy before live mutation.",
+    "liveMutationAuthorized": false
+  },
+  "allManagedShortcuts": [
+    {
+      "id": "desktop-profile-a-native",
+      "visibleName": "Claude Profile A",
+      "source": "native-desktop",
+      "profileId": "profile-a",
+      "locationKind": "desktop",
+      "targetKind": "native-launcher",
+      "launcherName": "claude-profile-a",
+      "groupingIdentity": "native-profile-a"
+    },
+    {
+      "id": "desktop-profile-b-native",
+      "visibleName": "Claude Profile B",
+      "source": "native-desktop",
+      "profileId": "profile-b",
+      "locationKind": "desktop",
+      "targetKind": "native-launcher",
+      "launcherName": "claude-profile-b",
+      "groupingIdentity": "native-profile-b"
+    },
+    {
+      "id": "start-profile-a-chrome",
+      "visibleName": "Claude Profile A (Chrome)",
+      "source": "chrome-start-menu",
+      "profileId": "profile-a",
+      "locationKind": "start-menu",
+      "targetKind": "chrome-profile",
+      "launcherName": "claude-profile-a",
+      "groupingIdentity": "chrome-profile-a"
+    },
+    {
+      "id": "start-profile-b-chrome",
+      "visibleName": "Claude Profile B (Chrome)",
+      "source": "chrome-start-menu",
+      "profileId": "profile-b",
+      "locationKind": "start-menu",
+      "targetKind": "chrome-profile",
+      "launcherName": "claude-profile-b",
+      "groupingIdentity": "chrome-profile-b"
+    }
+  ]
+}

package/scripts/profile-isolation-launchers/windows/shortcut-reconcile.ps1

@@ -0,0 +1,77 @@
+# Read-only reconciliation preview for managed Claude profile shortcuts.
+# Live mutation is refused while policy.liveMutationAuthorized is false.
+
+[CmdletBinding()]
+param(
+    [string]$ManifestPath = (Join-Path $PSScriptRoot 'shortcut-manifest.json'),
+    [string]$DesktopPath = [Environment]::GetFolderPath('Desktop'),
+    [string]$StartMenuPath = [Environment]::GetFolderPath('StartMenu'),
+    [string]$OutputPath,
+    [switch]$Apply
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$inventoryScript = Join-Path $PSScriptRoot 'shortcut-inventory.ps1'
+if (-not (Test-Path -LiteralPath $inventoryScript)) {
+    throw "inventory script missing: $inventoryScript"
+}
+
+$manifest = Get-Content -LiteralPath $ManifestPath -Raw | ConvertFrom-Json
+$inventoryJson = & $inventoryScript -ManifestPath $ManifestPath -DesktopPath $DesktopPath -StartMenuPath $StartMenuPath
+$inventory = $inventoryJson | ConvertFrom-Json
+
+$allActions = [System.Collections.Generic.List[object]]::new()
+foreach ($eachRow in $inventory.shortcuts) {
+    $actualPresent = [bool]$eachRow.exists
+    $hasSourceIdentity = -not [string]::IsNullOrWhiteSpace([string]$eachRow.source) -and
+        -not [string]::IsNullOrWhiteSpace([string]$eachRow.profileId) -and
+        -not [string]::IsNullOrWhiteSpace([string]$eachRow.groupingIdentity)
+    $status = if (-not $actualPresent) {
+        'missing'
+    }
+    elseif ($hasSourceIdentity) {
+        'present-unverified-target'
+    }
+    else {
+        'source-ambiguous'
+    }
+    $allActions.Add([pscustomobject]@{
+        id = $eachRow.id
+        visibleName = $eachRow.visibleName
+        source = $eachRow.source
+        profileId = $eachRow.profileId
+        groupingIdentity = $eachRow.groupingIdentity
+        desiredPresent = $true
+        actualPresent = $actualPresent
+        status = $status
+        expectedPath = $eachRow.expectedPath
+        mutation = 'none'
+    })
+}
+
+if ($Apply) {
+    if (-not [bool]$manifest.policy.liveMutationAuthorized) {
+        throw 'live shortcut mutation refused: policy.liveMutationAuthorized is false; owner confirmation required'
+    }
+    throw 'live shortcut mutation adapter is residual after owner confirmation (N1 apply path)'
+}
+
+$preview = [pscustomobject]@{
+    mode = 'preview-only'
+    policy = $manifest.policy
+    actionCount = $allActions.Count
+    actions = $allActions
+    liveMutationAuthorized = [bool]$manifest.policy.liveMutationAuthorized
+}
+
+$json = $preview | ConvertTo-Json -Depth 6
+if ($OutputPath) {
+    $directory = Split-Path -Parent $OutputPath
+    if ($directory -and -not (Test-Path -LiteralPath $directory)) {
+        New-Item -ItemType Directory -Path $directory | Out-Null
+    }
+    [IO.File]::WriteAllText($OutputPath, $json, [Text.UTF8Encoding]::new($false))
+}
+Write-Output $json