FileUse-Dock.ps1

<#
.SYNOPSIS
    Turn FileUse.sqlite into a folder-ecumenical icon board that opens at login.

.DESCRIPTION
    Reads the personal open-count database written by FileUse.ps1 and
    rebuilds C:\Users\<you>\FileUse\Dock\ as a flat folder of .lnk files.
    Each shortcut keeps the target's real icon. Paths can come from
    anywhere — that is the "ecumenical" part.

    Then (optional) drops a Startup shortcut that opens that folder
    in Explorer at logon. You set Extra Large Icons once; Windows
    remembers the view for that folder.

.EXAMPLE
    .\FileUse-Dock.ps1 -Sync
    .\FileUse-Dock.ps1 -Sync -Top 24 -Frecency
    .\FileUse-Dock.ps1 -Sync -InstallStartup
    .\FileUse-Dock.ps1 -Open
    .\FileUse-Dock.ps1 -UninstallStartup
#>
[CmdletBinding()]
param(
    [switch]$Sync,
    [switch]$Open,
    [switch]$InstallStartup,
    [switch]$UninstallStartup,
    [int]$Top = 24,
    [switch]$Frecency,
    [string]$DbPath,
    [string]$DockPath
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

if (-not $DbPath)  { $DbPath  = Join-Path $env:USERPROFILE 'FileUse\fileuse.sqlite' }
if (-not $DockPath){ $DockPath = Join-Path $env:USERPROFILE 'FileUse\Dock' }

$startupDir = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\Startup'
$startupLnk = Join-Path $startupDir 'FileUse Dock.lnk'

function Test-Pssqlite { [bool](Get-Module -ListAvailable -Name PSSQLite) }

function Get-FileUseRows {
    param([int]$N, [switch]$UseFrecency)

    if (-not (Test-Path -LiteralPath $DbPath)) {
        throw "No database at $DbPath. Run FileUse.ps1 -Init / -Harvest first."
    }

    if (Test-Pssqlite) {
        Import-Module PSSQLite -ErrorAction Stop
        if ($UseFrecency) {
            $q = @"
SELECT f.path, f.open_count, f.last_seen,
       ROUND((SELECT COALESCE(SUM(EXP(-0.0495 * (JULIANDAY('now','localtime') - JULIANDAY(o.opened_at)))),0)
              FROM opens o WHERE o.path = f.path), 3) AS score
FROM files f
ORDER BY score DESC, f.open_count DESC
LIMIT @n;
"@
        } else {
            $q = "SELECT path, open_count, last_seen FROM files ORDER BY last_seen DESC, open_count DESC LIMIT @n;"
        }
        return Invoke-SqliteQuery -DataSource $DbPath -Query $q -SqlParameters @{ n = $N }
    }

    $sqlite3 = Get-Command sqlite3.exe -ErrorAction SilentlyContinue
    if (-not $sqlite3) { throw 'Install PSSQLite (Install-Module PSSQLite -Scope CurrentUser) or sqlite3.exe' }

    if ($UseFrecency) {
        $q = "SELECT f.path, f.open_count, f.last_seen FROM files f ORDER BY f.last_seen DESC, f.open_count DESC LIMIT $N;"
    } else {
        $q = "SELECT path, open_count, last_seen FROM files ORDER BY last_seen DESC, open_count DESC LIMIT $N;"
    }
    $raw = & sqlite3.exe -header -csv $DbPath $q
    if (-not $raw) { return @() }
    return $raw | ConvertFrom-Csv
}

function New-SafeLnkName {
    param([int]$Index, [string]$TargetPath)
    $base = [IO.Path]::GetFileNameWithoutExtension($TargetPath)
    if ([string]::IsNullOrWhiteSpace($base)) { $base = 'item' }
    foreach ($c in [IO.Path]::GetInvalidFileNameChars()) {
        $base = $base.Replace([string]$c, '_')
    }
    if ($base.Length -gt 60) { $base = $base.Substring(0, 60) }
    return ('{0:D2} {1}.lnk' -f $Index, $base)
}

function Sync-FileUseDock {
    if (-not (Test-Path -LiteralPath $DockPath)) {
        New-Item -ItemType Directory -Path $DockPath -Force | Out-Null
    }

    $rows = @(Get-FileUseRows -N $Top -UseFrecency:$Frecency)
    $wanted = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
    $sh = New-Object -ComObject WScript.Shell
    $i = 1
    $written = 0

    foreach ($row in $rows) {
        $target = [string]$row.path
        if ([string]::IsNullOrWhiteSpace($target)) { continue }
        if (-not (Test-Path -LiteralPath $target)) { continue }

        $name = New-SafeLnkName -Index $i -TargetPath $target
        $lnkPath = Join-Path $DockPath $name
        [void]$wanted.Add($name)

        $sc = $sh.CreateShortcut($lnkPath)
        $sc.TargetPath = $target
        if (Test-Path -LiteralPath $target -PathType Container) {
            $sc.WorkingDirectory = $target
        } else {
            $sc.WorkingDirectory = [IO.Path]::GetDirectoryName($target)
        }
        $sc.Description = "opens={0} last={1}" -f $row.open_count, $row.last_seen
        $sc.Save()
        [void][Runtime.InteropServices.Marshal]::ReleaseComObject($sc)
        $i++
        $written++
    }

    Get-ChildItem -LiteralPath $DockPath -Filter '*.lnk' -File -ErrorAction SilentlyContinue |
        Where-Object { -not $wanted.Contains($_.Name) } |
        Remove-Item -Force

    [void][Runtime.InteropServices.Marshal]::ReleaseComObject($sh)
    Write-Host "Dock now has $written shortcut(s) in $DockPath"
}

function Install-DockStartup {
    if (-not (Test-Path -LiteralPath $DockPath)) {
        New-Item -ItemType Directory -Path $DockPath -Force | Out-Null
    }
    if (-not (Test-Path -LiteralPath $startupDir)) {
        New-Item -ItemType Directory -Path $startupDir -Force | Out-Null
    }
    $sh = New-Object -ComObject WScript.Shell
    $sc = $sh.CreateShortcut($startupLnk)
    $sc.TargetPath = "$env:WINDIR\explorer.exe"
    $sc.Arguments  = "`"$DockPath`""
    $sc.WorkingDirectory = $DockPath
    $sc.WindowStyle = 1
    $sc.Description = 'Open FileUse Dock folder at logon'
    $sc.Save()
    [void][Runtime.InteropServices.Marshal]::ReleaseComObject($sc)
    [void][Runtime.InteropServices.Marshal]::ReleaseComObject($sh)
    Write-Host "Startup shortcut written: $startupLnk"
    Write-Host "Set that folder to Extra Large Icons once. Windows will remember the view."
}

function Uninstall-DockStartup {
    if (Test-Path -LiteralPath $startupLnk) {
        Remove-Item -LiteralPath $startupLnk -Force
        Write-Host "Removed $startupLnk"
    } else {
        Write-Host 'No startup shortcut to remove.'
    }
}

function Open-FileUseDock {
    if (-not (Test-Path -LiteralPath $DockPath)) {
        New-Item -ItemType Directory -Path $DockPath -Force | Out-Null
    }
    Start-Process explorer.exe -ArgumentList "`"$DockPath`""
}

$did = $false
if ($Sync)            { Sync-FileUseDock; $did = $true }
if ($InstallStartup)  { Install-DockStartup; $did = $true }
if ($UninstallStartup){ Uninstall-DockStartup; $did = $true }
if ($Open)            { Open-FileUseDock; $did = $true }

if (-not $did) {
    Write-Host @"
FileUse Dock — icon board from the usage database

  .\FileUse-Dock.ps1 -Sync
  .\FileUse-Dock.ps1 -Sync -Top 24 -Frecency
  .\FileUse-Dock.ps1 -Sync -InstallStartup
  .\FileUse-Dock.ps1 -Open

Dock folder: $DockPath
Database:    $DbPath
"@
}