feat: install.cmd and a copy-based installer, README for the package

Co-Authored-By: Ovis Fast (Claude) <[email protected]>
This commit is contained in:
FactorandOvis Fast committed 2026-11-19 12:53:43 +01:00
1 parent 74c1dfaeb8
commit 7ec0c20989
3 files changed
+281 -132

No files matched your search

+52 -28
View File
@@ -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 <mods>\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-<date>` 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 <mods>\herdr-composer` and `herdr-app status` show problems).
+5
View File
@@ -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%
+224 -104
View File
@@ -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-<date> 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]@{})
# 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++
}
$global = $obj.global
if ($global.PSObject.Properties[$chord] -and $global.$chord -eq $action) {
Write-Host "keys.json already has $chord"
return $candidate
}
# 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."
}
}
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
}
if (-not (Test-Path -LiteralPath $KeysBak)) {
& 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"
}
$global | Add-Member -NotePropertyName $chord -NotePropertyValue $action -Force
}
$json = $obj | ConvertTo-Json -Depth 32
[IO.File]::WriteAllText($KeysFile, $json, (New-Object Text.UTF8Encoding($false)))
Write-Host "keys.json: $chord -> $action"
}
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.'
# 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++
}
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
}
}
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.'
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"
}
Write-Host "Removed junction $Junction"
if (Test-Path -LiteralPath $LayoutDst) {
Remove-Item -LiteralPath $LayoutDst -Force
Write-Host "Removed $LayoutDst"
}
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 $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"
# --- 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 {
Write-Host "Junction points at '$target' - recreating it for $ModSource"
Remove-Junction $Junction
$relink = $true
& git -C $Repo pull --ff-only
if ($LASTEXITCODE -ne 0) { Write-Warning "git pull --ff-only failed (exit $LASTEXITCODE) - 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"
} catch {
Write-Warning "git pull failed: $($_.Exception.Message) - installing what is here."
}
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