diff --git a/README.md b/README.md index 7d5a7f7..8ec2330 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,67 @@ -# herdrMario +# herdr-composer -Source of the `ovis-composer` Herdr mod (Unified Prompt Experience). +A message bar for [Herdr](https://herdr.dev) agents: one field under the terminal +that writes to the focused agent, with per-agent drafts that survive a restart, a +queue that waits for the agent's turn, history and favourites, `/` and `@` +suggestions, and one pipeline for attachments (drop, `+`, Ctrl+V). -- `mod/ovis-composer/` - the mod (ES modules; Herdr does not see changes behind the junction - see Reload) -- `layouts/ovis-composer.json` - its layout -- `tests/` - Node tests for the pure modules (`npm test`) -- `docs/superpowers/` - spec and plan +The package lives in [`herdr/herdr-composer/`](herdr/herdr-composer/) and has the +layout Herdr expects for shared mods and layouts: + +- `layouts/herdr-composer.json` - the layout (a clone of `main` with the composer block) +- `mods/herdr-composer/` - the mod (ES modules) +- `keys.json` - the key it expects (`ctrl-shift-space` focuses the composer) +- `RECIPE.md` - the brief to build it from scratch, and what it runs and reads + +Other folders: `tests/` (Node tests for the pure modules, `npm test`), `scripts/` +(the installer), `docs/` (spec, plan, verification). ## Install -```powershell -.\scripts\install.ps1 +Two ways, the same result. + +**1. Through an agent** (the way herdr.dev layouts are added): + +```text +Read ~/.config/herdr-app/AGENTS.md, then add this layout: clone http://git.mkali.pl/Factor/herdrMario.git and use the folder herdr/herdr-composer ``` -Idempotent. An existing real `mods\ovis-composer` directory is renamed to -`ovis-composer.bak-20261119` (never deleted), a junction to `mod\ovis-composer` -takes its place, and the layout is copied to `~\.config\herdr-app\layouts\` -(existing file backed up once as `.bak-20261119`). +**2. One command** (Windows): -The script ends with `herdr-app do layout.switch '{"name":"ovis-composer"}'`. -Check with `herdr-app check \ovis-composer` and `herdr-app status`. - -## Reload - -Herdr does **not** see changes to the mod files behind the junction: a running -copy keeps the code it loaded. After every edit of `mod\ovis-composer`: - -```powershell -.\scripts\install.ps1 -Reload +```cmd +git clone http://git.mkali.pl/Factor/herdrMario.git "%USERPROFILE%\herdrMario" && "%USERPROFILE%\herdrMario\install.cmd" ``` -It removes the junction and makes it again (the repo files stay), and Herdr -loads the mod from scratch. +The installer: + +- pulls the repo (`git pull --ff-only`, only when it is a clean clone; a failure is a warning); +- **copies** the mod to `~\.config\herdr-app\mods\herdr-composer` (a mirror) and the + layout to `layouts\herdr-composer.json`, so Herdr loads the new files by itself; +- merges `keys.json` of the package into yours (a backup is kept once as + `keys.json.bak-herdr-composer`; a key you bind to something else is left alone, with a warning); +- clears away the earlier version, `ovis-composer` (a junction is unlinked, a directory or + layout is moved to a `.bak-` copy, its key is removed) - your history, favourites, + drafts and queue are kept: the mod reads what the earlier version stored; +- runs `herdr-app check` on the mod and switches to the `herdr-composer` layout + (without `herdr-app` on the PATH these two are warnings, not errors). + +Files of this repo are never deleted. + +## Update + +Run `install.cmd` again (or ask the agent again). It is the same command: pull, copy, check. +There is no junction and no reload step - the copy is what Herdr sees. ## Uninstall -```powershell -.\scripts\install.ps1 -Uninstall +```cmd +install.cmd -Uninstall ``` -Removes the junction (the repo files stay), restores the `.bak-20261119` mod -directory, layout and `keys.json` backups, and switches to the `main` layout. +Removes `mods\herdr-composer`, `layouts\herdr-composer.json` and its key from `keys.json`, and +switches to the `main` layout. Only `.bak` copies stay. + +## Develop + +Edit the files in `herdr/herdr-composer/`, run `npm test`, then `install.cmd` to copy the +change into Herdr (`herdr-app check \herdr-composer` and `herdr-app status` show problems). diff --git a/install.cmd b/install.cmd new file mode 100644 index 0000000..6e47328 --- /dev/null +++ b/install.cmd @@ -0,0 +1,5 @@ +@echo off +rem Installs (or updates) the herdr-composer package. Run it again to update; +rem "install.cmd -Uninstall" removes it. See README.md. +powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0scripts\install.ps1" %* +exit /b %ERRORLEVEL% diff --git a/scripts/install.ps1 b/scripts/install.ps1 index 15e08ea..ffe1667 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -1,32 +1,52 @@ -# install.ps1 - link the repo's ovis-composer mod into the Herdr config. +# install.ps1 - install the herdr-composer package into the Herdr config. # -# .\scripts\install.ps1 install (idempotent) -# .\scripts\install.ps1 -Uninstall remove the junction, restore backups -# .\scripts\install.ps1 -Reload recreate the junction so Herdr loads the mod again +# install.cmd install or update (the same command both times) +# install.cmd -Uninstall remove it again # -# Herdr does NOT see changes behind the junction on its own: after editing -# mod\ovis-composer run -Reload (the junction is removed and made again, and -# Herdr reloads the mod). +# What install does (Windows PowerShell 5): +# 1. git pull --ff-only when this folder is a git clone without local changes +# (a failure is a warning - the install goes on with what is here); +# 2. COPIES herdr\herdr-composer\mods\herdr-composer to +# ~\.config\herdr-app\mods\herdr-composer (a mirror, so Herdr sees the new +# files and reloads the mod by itself) and the layout to +# ~\.config\herdr-app\layouts\herdr-composer.json; +# 3. merges the keys of the package (keys.json) into the person's keys.json +# (a backup is kept once as keys.json.bak-herdr-composer; a key the person +# already binds to something else is left alone, with a warning); +# 4. clears away the earlier version (ovis-composer): a junction is only +# unlinked, a directory or a layout file is moved to a .bak- copy, +# its key is taken out of keys.json - files of this repo are never deleted; +# 5. herdr-app check on the mod, then switches to the herdr-composer layout +# (no herdr-app on the PATH is a warning, not an error). # -# Works on Windows PowerShell 5. +# The person's data (history, favourites, drafts, the queue) is not touched: +# the mod reads what the earlier version kept (storage.js). [CmdletBinding()] -param([switch]$Uninstall, [switch]$Reload) +param([switch]$Uninstall) $ErrorActionPreference = 'Stop' -$Stamp = '20261119' +$Name = 'herdr-composer' +$OldName = 'ovis-composer' +$Stamp = Get-Date -Format 'yyyyMMdd' + $Repo = Split-Path -Parent $PSScriptRoot -$HerdrDir = Join-Path $env:USERPROFILE '.config\herdr-app' +$Package = Join-Path $Repo 'herdr\herdr-composer' +$ModSrc = Join-Path $Package "mods\$Name" +$LayoutSrc = Join-Path $Package "layouts\$Name.json" +$KeysSrc = Join-Path $Package 'keys.json' + +$HerdrDir = if ($env:HERDR_APP_HOME) { $env:HERDR_APP_HOME } else { Join-Path $env:USERPROFILE '.config\herdr-app' } $ModsDir = Join-Path $HerdrDir 'mods' -$Junction = Join-Path $ModsDir 'ovis-composer' -$ModBackup = "$Junction.bak-$Stamp" -$ModSource = Join-Path $Repo 'mod\ovis-composer' -$LayoutSrc = Join-Path $Repo 'layouts\ovis-composer.json' -$LayoutDst = Join-Path $HerdrDir 'layouts\ovis-composer.json' -$LayoutBak = "$LayoutDst.bak-$Stamp" +$LayoutsDir = Join-Path $HerdrDir 'layouts' +$ModDst = Join-Path $ModsDir $Name +$LayoutDst = Join-Path $LayoutsDir "$Name.json" $KeysFile = Join-Path $HerdrDir 'keys.json' -$KeysBak = "$KeysFile.bak-$Stamp" +$KeysBak = "$KeysFile.bak-$Name" + +$OurAction = "$Name.focus" +$OldAction = "$OldName.focus" function Test-Junction([string]$Path) { if (-not (Test-Path -LiteralPath $Path)) { return $false } @@ -34,121 +54,221 @@ function Test-Junction([string]$Path) { return [bool]($item.Attributes -band [IO.FileAttributes]::ReparsePoint) } +# rmdir on a junction removes only the link, never the target's contents. function Remove-Junction([string]$Path) { - # rmdir on a junction removes only the link, never the target's contents. cmd /c rmdir "`"$Path`"" | Out-Null if ($LASTEXITCODE -ne 0) { throw "rmdir failed for $Path" } } -# Merge "ctrl-shift-space": "ovis-composer.focus" into keys.json "global", -# leaving every other entry alone. Backs the file up once; idempotent. -function Install-KeyEntry { - $chord = 'ctrl-shift-space' - $action = 'ovis-composer.focus' - if (-not (Test-Path -LiteralPath $KeysFile)) { - $obj = [pscustomobject]@{ global = [pscustomobject]@{ $chord = $action } } - } else { - $raw = [IO.File]::ReadAllText($KeysFile) - $obj = $raw | ConvertFrom-Json - if ($obj -isnot [pscustomobject]) { throw "keys.json is not a JSON object - resolve by hand." } - if (-not $obj.PSObject.Properties['global']) { - $obj | Add-Member -NotePropertyName 'global' -NotePropertyValue ([pscustomobject]@{}) - } - $global = $obj.global - if ($global.PSObject.Properties[$chord] -and $global.$chord -eq $action) { - Write-Host "keys.json already has $chord" - return - } - if (-not (Test-Path -LiteralPath $KeysBak)) { - Copy-Item -LiteralPath $KeysFile -Destination $KeysBak - Write-Host "Backed up keys.json to $KeysBak" - } - $global | Add-Member -NotePropertyName $chord -NotePropertyValue $action -Force +# A path for a backup that does not exist yet. +function Get-FreeBackupPath([string]$Path) { + $candidate = "$Path.bak-$Stamp" + $n = 1 + while (Test-Path -LiteralPath $candidate) { + $candidate = "$Path.bak-$Stamp-$n" + $n++ } - $json = $obj | ConvertTo-Json -Depth 32 - [IO.File]::WriteAllText($KeysFile, $json, (New-Object Text.UTF8Encoding($false))) - Write-Host "keys.json: $chord -> $action" + return $candidate } -if ($Reload) { - if (-not (Test-Junction $Junction)) { throw "$Junction is not a junction - run install.ps1 first." } - Remove-Junction $Junction - if (-not (Test-Path -LiteralPath (Join-Path $ModSource 'main.js'))) { - throw 'Repo files vanished after removing the junction - aborting.' +# Nothing this script deletes or overwrites may be inside the repo. +function Assert-OutsideRepo([string]$Path) { + $full = [IO.Path]::GetFullPath($Path).TrimEnd([char]92) + $repo = [IO.Path]::GetFullPath($Repo).TrimEnd([char]92) + if ($full -ieq $repo -or $full.StartsWith($repo + '\', [StringComparison]::OrdinalIgnoreCase)) { + throw "$Path is inside the repo - refusing to touch it." } - cmd /c mklink /J "`"$Junction`"" "`"$ModSource`"" | Out-Null - if ($LASTEXITCODE -ne 0) { throw 'mklink /J failed' } - Write-Host "Junction recreated: $Junction -> $ModSource (Herdr loads the mod again)" - exit 0 } +function Test-HerdrApp { return [bool](Get-Command 'herdr-app' -ErrorAction SilentlyContinue) } + +function Switch-Layout([string]$LayoutName) { + if (-not (Test-HerdrApp)) { + Write-Warning "herdr-app is not on the PATH - switch the layout to '$LayoutName' by hand (ctrl-shift-l)." + return + } + & herdr-app do layout.switch --name $LayoutName + if ($LASTEXITCODE -ne 0) { + Write-Warning "layout.switch to '$LayoutName' failed (exit $LASTEXITCODE) - switch it by hand (ctrl-shift-l)." + } +} + +# --- keys.json ---------------------------------------------------------------- + +function Read-Json([string]$Path) { + $raw = [IO.File]::ReadAllText($Path) + if ($raw.Trim() -eq '') { return [pscustomobject]@{} } + $obj = $raw | ConvertFrom-Json + if ($obj -isnot [pscustomobject]) { throw "$Path is not a JSON object - resolve by hand." } + return $obj +} + +function Write-Json($Object, [string]$Path) { + $json = $Object | ConvertTo-Json -Depth 32 + [IO.File]::WriteAllText($Path, $json, (New-Object Text.UTF8Encoding($false))) +} + +function Backup-KeysOnce { + if ((Test-Path -LiteralPath $KeysFile) -and -not (Test-Path -LiteralPath $KeysBak)) { + Copy-Item -LiteralPath $KeysFile -Destination $KeysBak + Write-Host "Backed up keys.json to $KeysBak" + } +} + +# Takes out every key (in every section) that is bound to one of $Actions. +# Returns how many it removed. +function Remove-KeyActions($Keys, [string[]]$Actions) { + $removed = 0 + foreach ($section in @($Keys.PSObject.Properties)) { + if ($section.Value -isnot [pscustomobject]) { continue } + foreach ($key in @($section.Value.PSObject.Properties)) { + if ($Actions -contains [string]$key.Value) { + $section.Value.PSObject.Properties.Remove($key.Name) + $removed++ + } + } + } + return $removed +} + +# Merges the keys of the package into the person's: adds what is missing, keeps +# what is there, warns about a key the person binds to something else. +function Update-Keys { + if (-not (Test-Path -LiteralPath $KeysSrc)) { return } + $package = Read-Json $KeysSrc + + if (-not (Test-Path -LiteralPath $KeysFile)) { + Write-Json $package $KeysFile + Write-Host "keys.json created from the package" + return + } + + $mine = Read-Json $KeysFile + $changed = $false + + # The key of the earlier version points at an action that no longer exists. + if ((Remove-KeyActions $mine @($OldAction)) -gt 0) { + Backup-KeysOnce + $changed = $true + Write-Host "keys.json: removed the key of $OldName" + } + + foreach ($section in $package.PSObject.Properties) { + if (-not $mine.PSObject.Properties[$section.Name]) { + Backup-KeysOnce + $mine | Add-Member -NotePropertyName $section.Name -NotePropertyValue ([pscustomobject]@{}) + $changed = $true + } + $target = $mine.($section.Name) + foreach ($key in $section.Value.PSObject.Properties) { + $existing = $target.PSObject.Properties[$key.Name] + if ($existing) { + if ([string]$existing.Value -ne [string]$key.Value) { + Write-Warning "keys.json: '$($key.Name)' is already bound to '$($existing.Value)' - left as it is (the package wants '$($key.Value)')." + } + continue + } + Backup-KeysOnce + $target | Add-Member -NotePropertyName $key.Name -NotePropertyValue $key.Value + $changed = $true + Write-Host "keys.json: $($key.Name) -> $($key.Value)" + } + } + + if ($changed) { Write-Json $mine $KeysFile } else { Write-Host "keys.json already has the keys" } +} + +function Remove-OurKeys { + if (-not (Test-Path -LiteralPath $KeysFile)) { return } + $mine = Read-Json $KeysFile + if ((Remove-KeyActions $mine @($OurAction, $OldAction)) -gt 0) { + Backup-KeysOnce + Write-Json $mine $KeysFile + Write-Host "keys.json: removed the keys of $Name" + } +} + +# --- uninstall ---------------------------------------------------------------- + if ($Uninstall) { - if (Test-Junction $Junction) { - Remove-Junction $Junction - if (-not (Test-Path -LiteralPath (Join-Path $ModSource 'main.js'))) { - throw 'Repo files vanished after removing the junction - aborting.' - } - Write-Host "Removed junction $Junction" + Assert-OutsideRepo $ModDst + if (Test-Junction $ModDst) { + Remove-Junction $ModDst + Write-Host "Removed junction $ModDst" + } elseif (Test-Path -LiteralPath $ModDst) { + Remove-Item -LiteralPath $ModDst -Recurse -Force + Write-Host "Removed $ModDst" } - if ((Test-Path -LiteralPath $ModBackup) -and -not (Test-Path -LiteralPath $Junction)) { - Move-Item -LiteralPath $ModBackup -Destination $Junction - Write-Host "Restored $Junction" + if (Test-Path -LiteralPath $LayoutDst) { + Remove-Item -LiteralPath $LayoutDst -Force + Write-Host "Removed $LayoutDst" } - if (Test-Path -LiteralPath $LayoutBak) { - Copy-Item -LiteralPath $LayoutBak -Destination $LayoutDst -Force - Write-Host "Restored layout" - } - if (Test-Path -LiteralPath $KeysBak) { - Copy-Item -LiteralPath $KeysBak -Destination $KeysFile -Force - Write-Host "Restored keys.json" - } - herdr-app do layout.switch '{"name":"main"}' - if ($LASTEXITCODE -ne 0) { Write-Warning "layout.switch to main failed (exit $LASTEXITCODE) - switch the layout by hand." } + Remove-OurKeys + Switch-Layout 'main' exit 0 } -# 1. Mod directory -> junction to the repo. -$relink = $false -if (Test-Junction $Junction) { - $target = (Get-Item -LiteralPath $Junction -Force).Target - if ($target -is [array]) { $target = $target[0] } - if ($target -and ([IO.Path]::GetFullPath($target).TrimEnd([char]92) -ieq [IO.Path]::GetFullPath($ModSource).TrimEnd([char]92))) { - Write-Host "Junction already in place: $Junction" - } else { - Write-Host "Junction points at '$target' - recreating it for $ModSource" - Remove-Junction $Junction - $relink = $true +# --- install ------------------------------------------------------------------ + +if (-not (Test-Path -LiteralPath (Join-Path $ModSrc 'main.js'))) { throw "Package not found: $ModSrc" } +if (-not (Test-Path -LiteralPath $HerdrDir)) { throw "Herdr config not found: $HerdrDir (is Herdr installed and started once?)" } +Assert-OutsideRepo $ModDst +Assert-OutsideRepo $LayoutDst + +# 1. Update the repo when it is a clean clone. +if ((Test-Path -LiteralPath (Join-Path $Repo '.git')) -and (Get-Command git -ErrorAction SilentlyContinue)) { + try { + $dirty = & git -C $Repo status --porcelain + if ($dirty) { + Write-Warning 'Local changes in the repo - not updating it (git pull skipped).' + } else { + & git -C $Repo pull --ff-only + if ($LASTEXITCODE -ne 0) { Write-Warning "git pull --ff-only failed (exit $LASTEXITCODE) - installing what is here." } + } + } catch { + Write-Warning "git pull failed: $($_.Exception.Message) - installing what is here." } -} else { $relink = $true } -if ($relink) { - if (Test-Path -LiteralPath $Junction) { - if (Test-Path -LiteralPath $ModBackup) { throw "$ModBackup already exists - resolve by hand." } - Move-Item -LiteralPath $Junction -Destination $ModBackup - Write-Host "Backed up to $ModBackup" - } - cmd /c mklink /J "`"$Junction`"" "`"$ModSource`"" | Out-Null - if ($LASTEXITCODE -ne 0) { throw 'mklink /J failed' } - Write-Host "Junction: $Junction -> $ModSource" } -# gpui-kit.d.ts is git-ignored; keep a copy next to the sources for the editor. -$kitDst = Join-Path $ModSource 'gpui-kit.d.ts' -$kitSrc = if (Test-Path -LiteralPath (Join-Path $ModBackup 'gpui-kit.d.ts')) { Join-Path $ModBackup 'gpui-kit.d.ts' } else { Join-Path $HerdrDir 'gpui-kit.d.ts' } -if (-not (Test-Path -LiteralPath $kitDst) -and (Test-Path -LiteralPath $kitSrc)) { - Copy-Item -LiteralPath $kitSrc -Destination $kitDst +# 2. The earlier version (ovis-composer) goes out of the way. +$OldMod = Join-Path $ModsDir $OldName +if (Test-Junction $OldMod) { + Remove-Junction $OldMod + Write-Host "Removed the junction of the earlier version: $OldMod" +} elseif (Test-Path -LiteralPath $OldMod) { + $backup = Get-FreeBackupPath $OldMod + Move-Item -LiteralPath $OldMod -Destination $backup + Write-Host "Moved the earlier version to $backup" +} +$OldLayout = Join-Path $LayoutsDir "$OldName.json" +if (Test-Path -LiteralPath $OldLayout) { + $backup = Get-FreeBackupPath $OldLayout + Move-Item -LiteralPath $OldLayout -Destination $backup + Write-Host "Moved the earlier layout to $backup" } -# 2. Layout (back up the existing file once). -if ((Test-Path -LiteralPath $LayoutDst) -and -not (Test-Path -LiteralPath $LayoutBak)) { - Copy-Item -LiteralPath $LayoutDst -Destination $LayoutBak - Write-Host "Backed up layout to $LayoutBak" -} +# 3. The mod: a mirror copy. gpui-kit.d.ts and jsconfig.json are the editor's, +# written by Herdr next to the mod - they are not part of the copy and are not +# purged from the destination. +New-Item -ItemType Directory -Force -Path $ModsDir | Out-Null +if (Test-Junction $ModDst) { Remove-Junction $ModDst } +robocopy $ModSrc $ModDst /MIR /XF gpui-kit.d.ts jsconfig.json /NFL /NDL /NJH /NJS /NP | Out-Null +if ($LASTEXITCODE -ge 8) { throw "robocopy failed (exit $LASTEXITCODE)" } +Write-Host "Mod copied: $ModDst" + +# 4. The layout. +New-Item -ItemType Directory -Force -Path $LayoutsDir | Out-Null Copy-Item -LiteralPath $LayoutSrc -Destination $LayoutDst -Force -Write-Host "Layout copied" +Write-Host "Layout copied: $LayoutDst" -# 3. Key binding (Task 2). -Install-KeyEntry +# 5. Keys. +Update-Keys -# 4. Show the layout. -herdr-app do layout.switch '{"name":"ovis-composer"}' -if ($LASTEXITCODE -ne 0) { Write-Warning "layout.switch to ovis-composer failed (exit $LASTEXITCODE) - switch the layout by hand." } +# 6. Check the mod, show the layout. +if (Test-HerdrApp) { + & herdr-app check $ModDst + if ($LASTEXITCODE -ne 0) { Write-Warning "herdr-app check reported a problem (exit $LASTEXITCODE)." } +} else { + Write-Warning 'herdr-app is not on the PATH - the mod was not checked.' +} +Switch-Layout $Name