win-nice 0.1.0

package/bin/realtime.ps1

@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# win-nice: managed-file
+# DANGEROUS: REALTIME_PRIORITY_CLASS outranks the OS's own input/audio/UI threads.
+# A busy realtime-priority process can make the desktop (mouse, keyboard, everything)
+# stop responding - the exact failure mode this whole project exists to prevent. See
+# README before using this.
+# No param(): nothing here needs a named parameter, and $args sidesteps
+# PowerShell's parameter binder entirely - see cap.ps1 for why that matters.
+$Command = $args
+
+if (-not $Command -or $Command.Count -eq 0) {
+    Write-Error "usage: realtime <command> [args...]"
+    exit 1
+}
+
+# Fallback command line for when the target isn't a directly-launchable .exe (see
+# RealtimeLauncher.Run below) - re-parsed by cmd.exe (via "cmd.exe /c"), so quoting must
+# neutralize its operators (&|<>^) and not just whitespace - see cap.ps1 for the
+# same logic and its documented "%" limitation. realtime.bat has its own, more
+# severe "%" caveat (see there) that applies before this script ever runs.
+$commandLine = ($Command | ForEach-Object {
+    $escaped = $_ -replace '"', '\"'
+    if ($escaped -eq '' -or $escaped -match '[\s"&|<>^]') { '"' + $escaped + '"' } else { $escaped }
+}) -join ' '
+
+$source = @"
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class RealtimeLauncher
+{
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    struct STARTUPINFO
+    {
+        public int cb;
+        public string lpReserved;
+        public string lpDesktop;
+        public string lpTitle;
+        public int dwX;
+        public int dwY;
+        public int dwXSize;
+        public int dwYSize;
+        public int dwXCountChars;
+        public int dwYCountChars;
+        public int dwFillAttribute;
+        public int dwFlags;
+        public short wShowWindow;
+        public short cbReserved2;
+        public IntPtr lpReserved2;
+        public IntPtr hStdInput;
+        public IntPtr hStdOutput;
+        public IntPtr hStdError;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct PROCESS_INFORMATION
+    {
+        public IntPtr hProcess;
+        public IntPtr hThread;
+        public int dwProcessId;
+        public int dwThreadId;
+    }
+
+    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+    static extern bool CreateProcess(string lpApplicationName, StringBuilder lpCommandLine,
+        IntPtr lpProcessAttributes, IntPtr lpThreadAttributes, bool bInheritHandles,
+        uint dwCreationFlags, IntPtr lpEnvironment, string lpCurrentDirectory,
+        ref STARTUPINFO lpStartupInfo, out PROCESS_INFORMATION lpProcessInformation);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint WaitForSingleObject(IntPtr hHandle, uint dwMilliseconds);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool GetExitCodeProcess(IntPtr hProcess, out uint lpExitCode);
+
+    [DllImport("kernel32.dll")]
+    static extern bool CloseHandle(IntPtr hObject);
+
+    // Standard MSVCRT/CommandLineToArgvW quoting: safe for a directly-launched .exe's
+    // own argv parsing. No cmd.exe involved on this path, so none of its operator or
+    // "%" expansion semantics apply - this is the safe path, used whenever possible.
+    static string ArgvQuote(string arg)
+    {
+        if (arg.Length > 0 && arg.IndexOfAny(new char[] { ' ', '\t', '\n', '\v', '"' }) < 0)
+            return arg;
+
+        var result = new StringBuilder();
+        result.Append('"');
+        int backslashes = 0;
+        foreach (char c in arg)
+        {
+            if (c == '\\')
+            {
+                backslashes++;
+            }
+            else if (c == '"')
+            {
+                result.Append('\\', backslashes * 2 + 1);
+                result.Append('"');
+                backslashes = 0;
+            }
+            else
+            {
+                if (backslashes > 0) { result.Append('\\', backslashes); backslashes = 0; }
+                result.Append(c);
+            }
+        }
+        if (backslashes > 0) result.Append('\\', backslashes * 2);
+        result.Append('"');
+        return result.ToString();
+    }
+
+    static string BuildArgvCommandLine(string[] argv)
+    {
+        var parts = new string[argv.Length];
+        for (int i = 0; i < argv.Length; i++) parts[i] = ArgvQuote(argv[i]);
+        return string.Join(" ", parts);
+    }
+
+    // Priority is passed via dwCreationFlags, applied atomically at creation - no
+    // Job Object needed. Windows' CreateProcess inherits IDLE/BELOW_NORMAL priority
+    // by default to children that don't request a priority of their own; REALTIME is
+    // NOT inherited by default (see README).
+    public static int Run(uint priorityClass, string[] argv, string cmdExeCommandLine)
+    {
+        var si = new STARTUPINFO();
+        si.cb = Marshal.SizeOf(si);
+        PROCESS_INFORMATION pi = new PROCESS_INFORMATION();
+
+        // See cap.ps1 for why .bat/.cmd targets skip the direct attempt entirely:
+        // CreateProcess silently re-invokes them through cmd.exe on its own, using
+        // unescaped text, instead of failing the way a genuinely missing exe would.
+        bool isBatOrCmd = argv.Length > 0 && (
+            argv[0].EndsWith(".bat", StringComparison.OrdinalIgnoreCase) ||
+            argv[0].EndsWith(".cmd", StringComparison.OrdinalIgnoreCase));
+
+        bool created = false;
+        if (!isBatOrCmd)
+        {
+            var directCommandLine = new StringBuilder(BuildArgvCommandLine(argv));
+            created = CreateProcess(null, directCommandLine, IntPtr.Zero, IntPtr.Zero, true,
+                priorityClass, IntPtr.Zero, null, ref si, out pi);
+        }
+
+        if (!created)
+        {
+            // Falling back to cmd.exe /c: a literal "%" in any argument could now
+            // trigger environment-variable expansion (cmd.exe pairs up "%" characters
+            // across the whole command line, even across separate arguments) and
+            // change what actually runs. Fail loudly here instead of silently risking
+            // that - there's no reliable per-character escape for "%" at this level.
+            foreach (var a in argv)
+            {
+                if (a.IndexOf('%') >= 0)
+                    throw new InvalidOperationException(
+                        "Refusing to run: argument contains '%' and the target needs the cmd.exe " +
+                        "fallback (not a directly-launchable .exe), where '%' can trigger unintended " +
+                        "environment-variable expansion. See README's Argument handling section.");
+            }
+
+            string cmdExe = Environment.SystemDirectory + "\\cmd.exe";
+            // /d: skip HKCU AutoRun (user-writable registry key). /v:off: disable delayed
+            // expansion so "!var!" in an argument can't be expanded. /s plus the extra outer
+            // quote pair: cmd's /S rule strips exactly that outer pair and leaves the rest of
+            // the string untouched - without /S, cmd strips the first and last quote of the
+            // whole line instead, which breaks quoting whenever the target path itself needs
+            // quotes AND another argument is also quoted.
+            var shellCommandLine = new StringBuilder("\"" + cmdExe + "\" /d /v:off /s /c \"" + cmdExeCommandLine + "\"");
+            created = CreateProcess(null, shellCommandLine, IntPtr.Zero, IntPtr.Zero, true,
+                priorityClass, IntPtr.Zero, null, ref si, out pi);
+            if (!created)
+                throw new InvalidOperationException("CreateProcess failed: " + Marshal.GetLastWin32Error());
+        }
+
+        WaitForSingleObject(pi.hProcess, 0xFFFFFFFF);
+
+        uint exitCode;
+        GetExitCodeProcess(pi.hProcess, out exitCode);
+
+        CloseHandle(pi.hThread);
+        CloseHandle(pi.hProcess);
+
+        return (int)exitCode;
+    }
+}
+"@
+
+Add-Type -TypeDefinition $source -Language CSharp
+
+$REALTIME_PRIORITY_CLASS = 0x00000100
+try {
+    exit ([RealtimeLauncher]::Run($REALTIME_PRIORITY_CLASS, [string[]]$Command, $commandLine))
+} catch {
+    Write-Error $_.Exception.InnerException.Message
+    exit 1
+}

package/bin/uiup

@@ -0,0 +1,11 @@
+#!/bin/sh
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# win-nice: managed-file
+# Git Bash ignores PATHEXT for bare-name resolution; this shim covers that shell.
+# MSYS2_ARG_CONV_EXCL='*' stops Git Bash/MSYS from rewriting user arguments
+# (e.g. /c, /d, C:\...) into Windows paths before the exec; the shim's own
+# .ps1 path is converted explicitly with cygpath -w so -File gets a Windows path.
+MSYS2_ARG_CONV_EXCL='*'
+export MSYS2_ARG_CONV_EXCL
+script=$(cygpath -w "$(dirname "$0")/uiup.ps1" 2>/dev/null) || script="$(dirname "$0")/uiup.ps1"
+exec powershell -NoProfile -ExecutionPolicy Bypass -File "$script" "$@"

package/bin/uiup.bat

@@ -0,0 +1,4 @@
+@echo off
+:: SPDX-License-Identifier: MIT OR Apache-2.0
+:: win-nice: managed-file
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0uiup.ps1"

package/bin/uiup.ps1

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# win-nice: managed-file
+param([switch]$SelfElevated)
+
+$targets = @('explorer', 'dwm', 'sihost', 'ShellExperienceHost', 'StartMenuExperienceHost', 'StartMenu', 'SearchApp', 'audiodg')
+
+$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+if (-not $isAdmin) {
+    Write-Host "Not elevated - requesting admin rights (dwm/sihost run under a different account)..."
+    try {
+        $p = Start-Process powershell -Verb RunAs -ArgumentList @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', "`"$PSCommandPath`"", '-SelfElevated') -Wait -PassThru
+        exit $p.ExitCode
+    } catch {
+        Write-Error "Elevation was cancelled or failed: $($_.Exception.Message)"
+        exit 1
+    }
+}
+
+$rows = foreach ($name in $targets) {
+    $procs = Get-Process -Name $name -ErrorAction SilentlyContinue
+    if (-not $procs) {
+        [PSCustomObject]@{ Name = $name; Id = '-'; Old = '-'; New = 'not running' }
+        continue
+    }
+    foreach ($proc in $procs) {
+        $old = $proc.PriorityClass
+        try {
+            $proc.PriorityClass = 'High'
+            [PSCustomObject]@{ Name = $name; Id = $proc.Id; Old = $old; New = 'High' }
+        } catch {
+            [PSCustomObject]@{ Name = $name; Id = $proc.Id; Old = $old; New = "FAILED: $($_.Exception.Message)" }
+        }
+    }
+}
+
+$rows | Format-Table -AutoSize
+if ($SelfElevated) {
+    Write-Host ""
+    Write-Host "Done. Press Enter to close..."
+    Read-Host | Out-Null
+}

package/install/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+const { install } = require('./install');
+const { uninstall } = require('./uninstall');
+const { installSkill, uninstallSkill } = require('./skill');
+const paths = require('./paths');
+const manifest = require('./manifest');
+
+function status() {
+  const data = manifest.read(paths.manifestPath());
+  if (!data) {
+    console.log('win-nice is not installed.');
+    return;
+  }
+  console.log(`win-nice ${data.version} installed at ${data.installedAt}`);
+  console.log(`bin dir: ${data.binDir}`);
+  console.log(`files: ${Array.isArray(data.files) ? data.files.join(', ') : '(manifest is malformed - run reinstall)'}`);
+}
+
+function main() {
+  const cmd = process.argv[2] || 'install';
+  const updatePath = !process.env.WIN_NICE_NO_PATH;
+  switch (cmd) {
+    case 'install':
+      install({ updatePath });
+      break;
+    case 'uninstall':
+      uninstall({ updatePath });
+      break;
+    case 'reinstall':
+      uninstall({ updatePath });
+      install({ updatePath });
+      break;
+    case 'status':
+      status();
+      break;
+    case 'skill': {
+      const sub = process.argv[3];
+      if (sub === 'install') {
+        const results = installSkill();
+        if (results.some((r) => !r.installed)) process.exitCode = 1;
+      } else if (sub === 'uninstall') {
+        const results = uninstallSkill();
+        // 'missing' (nothing to remove) isn't a failure; a stripped/foreign
+        // marker (skip-due-to-conflict) is - it means removal didn't happen
+        // when a real file was there.
+        if (results.some((r) => !r.removed && r.reason !== 'missing')) process.exitCode = 1;
+      } else {
+        console.error(`unknown skill command: ${sub}`);
+        console.error('usage: win-nice skill <install|uninstall>');
+        process.exitCode = 1;
+      }
+      break;
+    }
+    default:
+      console.error(`unknown command: ${cmd}`);
+      console.error('usage: win-nice <install|uninstall|reinstall|status|skill>');
+      process.exitCode = 1;
+  }
+}
+
+main();

package/install/install.js

@@ -0,0 +1,79 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const paths = require('./paths');
+const manifest = require('./manifest');
+const { removeManagedFile } = require('./uninstall');
+const pkg = require('../package.json');
+
+const SOURCE_BIN = path.join(__dirname, '..', 'bin');
+
+function listSourceFiles() {
+  // .bat/.ps1 launchers plus their extensionless POSIX shell shims (bin/<tool>,
+  // no dot) - the sibling Git Bash needs since it ignores PATHEXT on bare names.
+  return fs.readdirSync(SOURCE_BIN).filter((f) => f.endsWith('.bat') || f.endsWith('.ps1') || !f.includes('.'));
+}
+
+// Guards against `npm install`/`npm test` inside a source checkout silently
+// touching the real system PATH - only a genuine package install (running from
+// inside someone's node_modules) or an explicit WIN_NICE_HOME override proceeds.
+function isSourceCheckout() {
+  return fs.existsSync(path.join(__dirname, '..', '.git'));
+}
+
+// `npm install -g win-nice@newer` only runs postinstall (this function) - unlike
+// `win-nice reinstall`, which does uninstall()+install(), it never diffs against
+// what a previous version left behind. Without this, a tool dropped in a newer
+// version stays orphaned in binDir forever. Safe to call before the target dir
+// even exists (read() returns null, staleNames is empty).
+function cleanupStaleFiles(dir, currentFiles) {
+  const previous = manifest.read(paths.manifestPath());
+  if (!previous || !Array.isArray(previous.files)) return;
+
+  const currentSet = new Set(currentFiles);
+  const staleNames = previous.files.filter((name) => !currentSet.has(name));
+  const previousDir = previous.binDir || dir;
+  for (const name of staleNames) {
+    removeManagedFile(path.join(previousDir, name), dir, { requireMarker: false });
+  }
+}
+
+function install({ updatePath = true } = {}) {
+  if (!process.env.WIN_NICE_HOME && isSourceCheckout()) {
+    console.log(
+      'Running from a source checkout - skipping real install. ' +
+        'Set WIN_NICE_HOME to force a target directory, or install the published package.'
+    );
+    return null;
+  }
+
+  const dir = paths.binDir();
+  fs.mkdirSync(dir, { recursive: true });
+
+  const files = listSourceFiles();
+  cleanupStaleFiles(dir, files);
+  for (const name of files) {
+    fs.copyFileSync(path.join(SOURCE_BIN, name), path.join(dir, name));
+  }
+
+  manifest.write(paths.manifestPath(), {
+    version: pkg.version,
+    installedAt: new Date().toISOString(),
+    binDir: dir,
+    files,
+  });
+
+  if (updatePath) {
+    const current = paths.readUserPath();
+    const next = paths.addToPathString(current, dir);
+    if (next !== current) {
+      paths.writeUserPath(next);
+      console.log(`Added ${dir} to your PATH. Restart your terminal for it to take effect.`);
+    }
+  }
+
+  console.log(`win-nice ${pkg.version} installed: ${files.join(', ')} -> ${dir}`);
+  return { dir, files };
+}
+
+module.exports = { install, listSourceFiles, isSourceCheckout };

package/install/manifest.js

@@ -0,0 +1,29 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = 'win-nice: managed-file';
+
+function hasMarker(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8').includes(MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function write(manifestFile, data) {
+  fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
+  fs.writeFileSync(manifestFile, JSON.stringify(data, null, 2) + '\n');
+}
+
+function read(manifestFile) {
+  if (!fs.existsSync(manifestFile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { MARKER, hasMarker, write, read };

package/install/paths.js

@@ -0,0 +1,141 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// WIN_NICE_HOME overrides the install root - used by tests and by anyone who
+// wants a non-default location. Real installs default to %LOCALAPPDATA%\win-nice.
+function installRoot() {
+  if (process.env.WIN_NICE_HOME) return process.env.WIN_NICE_HOME;
+  const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+  return path.join(localAppData, 'win-nice');
+}
+
+function binDir() {
+  return path.join(installRoot(), 'bin');
+}
+
+function manifestPath() {
+  return path.join(installRoot(), 'install-manifest.json');
+}
+
+function normalize(p) {
+  return path.normalize(p).replace(/\\+$/, '').toLowerCase();
+}
+
+// Comparison-only stand-in for [Environment]::ExpandEnvironmentVariables: %VAR%
+// references resolve case-insensitively against the current process env (Windows
+// var names are case-insensitive and so is process.env lookup on win32); unknown
+// or malformed references stay literal text instead of throwing or vanishing.
+// Never used on anything we write back - the raw registry string is preserved
+// exactly; this only lets add/remove recognize a raw %VAR% entry (e.g.
+// %LOCALAPPDATA%\win-nice\bin) as the same location as its expanded form.
+function expandEnvRefs(s) {
+  return s.replace(/%([^%]*)%/g, (whole, name) => {
+    const value = process.env[name];
+    return value === undefined ? whole : value;
+  });
+}
+
+// Two PATH entries point at the same location if their %VAR% references expand
+// to the same directories, even though the registry stores the raw text.
+function comparisonForm(p) {
+  return normalize(expandEnvRefs(p));
+}
+
+function addToPathString(currentPath, dir) {
+  const parts = currentPath.split(';').filter(Boolean);
+  const target = comparisonForm(dir);
+  const already = parts.some((p) => comparisonForm(p) === target);
+  if (already) return currentPath;
+  return [...parts, dir].join(';');
+}
+
+function removeFromPathString(currentPath, dir) {
+  const parts = currentPath.split(';').filter(Boolean);
+  const target = comparisonForm(dir);
+  return parts.filter((p) => comparisonForm(p) !== target).join(';');
+}
+
+function runPowershell(script, extraEnv) {
+  return execFileSync('powershell', ['-NoProfile', '-Command', script], {
+    encoding: 'utf8',
+    env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+  });
+}
+
+// Reads a registry string value without OEM-codepage corruption and without %VAR%
+// expansion. Stdout carries Base64 (pure ASCII, safe under any console code page)
+// instead of the raw value - PowerShell 5.1 writes redirected stdout in the console's
+// OEM code page, not UTF-8, which corrupts any non-ASCII character otherwise.
+// keyPath/valueName travel via env vars (UTF-16 on Windows) so they're never
+// re-encoded either. Exported standalone so tests can hit a scratch key, never Path.
+function readRegistryString(keyPath, valueName) {
+  const script = [
+    '$v = (Get-Item -LiteralPath $env:WIN_NICE_REG_KEY).GetValue(',
+    '  $env:WIN_NICE_REG_VALUE, \'\', \'DoNotExpandEnvironmentNames\')',
+    '[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$v))',
+  ].join('\n');
+  const out = runPowershell(script, { WIN_NICE_REG_KEY: keyPath, WIN_NICE_REG_VALUE: valueName });
+  return Buffer.from(out.trim(), 'base64').toString('utf8');
+}
+
+// Writes a registry string value, preserving REG_EXPAND_SZ if that was already the
+// value's kind (so %VAR% entries like WindowsApps survive a round trip instead of
+// being frozen into literals). Creates the key if missing, for scratch-key tests.
+function writeRegistryString(keyPath, valueName, value) {
+  const script = [
+    'if (-not (Test-Path -LiteralPath $env:WIN_NICE_REG_KEY)) {',
+    '  New-Item -Path $env:WIN_NICE_REG_KEY -Force | Out-Null',
+    '}',
+    '$kind = \'String\'',
+    'try {',
+    '  if ((Get-Item -LiteralPath $env:WIN_NICE_REG_KEY).GetValueKind($env:WIN_NICE_REG_VALUE) -eq [Microsoft.Win32.RegistryValueKind]::ExpandString) {',
+    '    $kind = \'ExpandString\'',
+    '  }',
+    '} catch {}',
+    'Set-ItemProperty -LiteralPath $env:WIN_NICE_REG_KEY -Name $env:WIN_NICE_REG_VALUE -Value $env:WIN_NICE_REG_NEW_VALUE -Type $kind',
+  ].join('\n');
+  runPowershell(script, {
+    WIN_NICE_REG_KEY: keyPath,
+    WIN_NICE_REG_VALUE: valueName,
+    WIN_NICE_REG_NEW_VALUE: value,
+  });
+}
+
+// A raw registry write (unlike [Environment]::SetEnvironmentVariable) doesn't notify
+// running processes. Broadcast WM_SETTINGCHANGE so Explorer/new shells pick it up.
+function broadcastEnvironmentChange() {
+  const script = [
+    'Add-Type -Namespace WinNice -Name NativeMethods -MemberDefinition \'[DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Auto)] public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wParam, string lParam, uint fuFlags, uint uTimeout, out UIntPtr lpdwResult);\'',
+    '$result = [UIntPtr]::Zero',
+    '[WinNice.NativeMethods]::SendMessageTimeout([IntPtr]0xffff, 0x1A, [UIntPtr]::Zero, "Environment", 2, 5000, [ref]$result) | Out-Null',
+  ].join('\n');
+  runPowershell(script);
+}
+
+const USER_ENV_KEY = 'HKCU:\\Environment';
+
+// Real registry reads/writes - via the registry directly rather than
+// [Environment]::...('User') (OEM-codepage + expansion pitfalls, see
+// readRegistryString) or `setx` (truncates PATH silently past ~1024 chars).
+function readUserPath() {
+  return readRegistryString(USER_ENV_KEY, 'Path');
+}
+
+function writeUserPath(newPath) {
+  writeRegistryString(USER_ENV_KEY, 'Path', newPath);
+  broadcastEnvironmentChange();
+}
+
+module.exports = {
+  installRoot,
+  binDir,
+  manifestPath,
+  addToPathString,
+  removeFromPathString,
+  readUserPath,
+  writeUserPath,
+  readRegistryString,
+  writeRegistryString,
+};

package/install/skill.js

@@ -0,0 +1,68 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MARKER = '<!-- win-nice: managed-skill -->';
+const SOURCE = path.join(__dirname, '..', 'skills', 'win-nice', 'SKILL.md');
+
+// WIN_NICE_SKILL_HOME overrides where these live - used by tests, mirroring
+// WIN_NICE_HOME for the bin/ installer.
+function homeDir() {
+  return process.env.WIN_NICE_SKILL_HOME || os.homedir();
+}
+
+function targets() {
+  const home = homeDir();
+  return [
+    path.join(home, '.claude', 'skills', 'win-nice', 'SKILL.md'),
+    // Not ~/.codex/skills - Codex CLI's current personal-skill location is
+    // $HOME/.agents/skills (the open agentskills.io standard's user scope;
+    // .codex/skills was an earlier/incorrect assumption, since corrected).
+    path.join(home, '.agents', 'skills', 'win-nice', 'SKILL.md'),
+  ];
+}
+
+// ~/.claude/skills and ~/.agents/skills are shared namespaces, not a directory
+// win-nice owns exclusively (unlike %LOCALAPPDATA%\win-nice\bin for the bin/
+// installer) - a "win-nice" folder there could belong to someone/something else
+// entirely, so installing must never blindly overwrite an existing file.
+function installSkill() {
+  const content = fs.readFileSync(SOURCE, 'utf8');
+  const results = [];
+  for (const target of targets()) {
+    if (fs.existsSync(target) && !fs.readFileSync(target, 'utf8').includes(MARKER)) {
+      results.push({ file: target, installed: false, reason: 'already exists (not ours - refusing to overwrite)' });
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+    results.push({ file: target, installed: true });
+  }
+  for (const r of results) {
+    console.log(r.installed ? `installed skill: ${r.file}` : `skipped ${r.file} (${r.reason})`);
+  }
+  return results;
+}
+
+function uninstallSkill() {
+  const results = [];
+  for (const target of targets()) {
+    if (!fs.existsSync(target)) {
+      results.push({ file: target, removed: false, reason: 'missing' });
+      continue;
+    }
+    if (!fs.readFileSync(target, 'utf8').includes(MARKER)) {
+      results.push({ file: target, removed: false, reason: 'marker missing (modified by user?)' });
+      continue;
+    }
+    fs.unlinkSync(target);
+    results.push({ file: target, removed: true });
+  }
+  for (const r of results) {
+    console.log(r.removed ? `removed ${r.file}` : `skipped ${r.file} (${r.reason})`);
+  }
+  return results;
+}
+
+module.exports = { installSkill, uninstallSkill, targets, MARKER };