harnery 0.43.0 → 0.44.0

package/dist/lib/browser/windows-chrome.js

@@ -5,18 +5,19 @@ import { join } from "node:path";
 /**
  * Sign-in through the Windows host's Google Chrome when running under WSL.
  *
- * Some sign-in flows (X is the reported case) reject every browser running
- * inside WSL, including a plain Linux Google Chrome with nothing attached:
- * the sign-in request comes back "429 Too Many Requests" while the same
- * account signs in from the Windows desktop browser without trouble. The
- * Windows Chrome is the client those flows accept, so `browse --login
- * --plain` under WSL opens it on a dedicated Windows-side profile. The
- * person signs in there with nothing attached. Afterwards the profile is
- * reopened headless for a moment, its cookies for the sign-in site are read
- * through the DevTools protocol, and they are merged into the shared cookie
- * store that later `browse` runs attach. The Windows profile cannot be shared
- * with Linux Chromium directly because Windows encrypts its cookie database
- * with keys only Windows can read.
+ * Some sign-in flows reject every browser running inside WSL, including a
+ * plain Linux Google Chrome with nothing attached: the sign-in request comes
+ * back "429 Too Many Requests" while the same account signs in from the
+ * Windows desktop browser without trouble. The Windows Chrome is the client
+ * those flows accept, so `browse --login --plain` under WSL opens it on a
+ * dedicated Windows-side profile. The person signs in there with nothing
+ * attached. Afterwards the profile is reopened headless for a moment with its
+ * last session restored, its cookies for the sign-in site (browser-session
+ * cookies included) and its open pages on that site are read through the
+ * DevTools protocol, and the cookies are merged into the shared cookie store
+ * that later `browse` runs attach. The Windows profile cannot be shared with
+ * Linux Chromium directly because Windows encrypts its cookie database with
+ * keys only Windows can read.
  *
  * Under WSL2's default NAT networking the Windows loopback port is not
  * reachable from Linux, so the DevTools conversation runs inside a short
@@ -79,96 +80,284 @@ export function cookiesForDomain(cdpCookies, domain) {
     }));
 }
 /**
- * PowerShell that does the whole read on the Windows side: start Chrome
- * headless on the profile, wait for the DevToolsActivePort file it writes,
- * read every cookie with `Storage.getCookies`, write the raw response to
- * stdout, and close the browser. WSL never touches the profile folder, which
- * it may not be able to list. Every wait carries a deadline.
+ * Regular expression, valid in both JavaScript and .NET, that matches a Chrome
+ * command line running on `profileWindows`. It matches the `--user-data-dir`
+ * argument exactly, with or without quotes around the path, so `...\profile`
+ * never matches `...\profile-2`. Quotes are written as `\x22` so the pattern
+ * survives being passed to PowerShell as an argument. Case-insensitive use is
+ * intended, as Windows paths are.
  */
-export function harvestScript() {
+export function profileCommandLinePattern(profileWindows) {
+    const path = profileWindows.replace(/\\+$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return `--user-data-dir=\\x22?${path}\\\\?(\\x22|\\s|$)`;
+}
+/** PowerShell function listing the Chrome processes whose command line matches `$Pattern`. */
+const PROFILE_PROCESS_FUNCTION = "function Get-ProfileChrome { @(Get-CimInstance Win32_Process -Filter \"Name='chrome.exe'\" | Where-Object { $_.CommandLine -and $_.CommandLine -match $Pattern }) }";
+/**
+ * PowerShell that throws while any Chrome is still running on the profile: a
+ * second Chrome on the same profile hands its work to the first and exits.
+ */
+const REFUSE_OPEN_PROFILE_LINES = [
+    PROFILE_PROCESS_FUNCTION,
+    "$alive = Get-ProfileChrome",
+    "if ($alive.Count -gt 0) { throw \"Chrome is still running on the sign-in profile (process $(($alive | ForEach-Object { $_.ProcessId }) -join ', ')). Close that window and try again.\" }",
+];
+/**
+ * PowerShell that starts Chrome headless on `$Profile` with `extraArgs`, waits
+ * for the DevToolsActivePort file it writes, and connects to the browser
+ * endpoint, defining `Send`, `Recv`, and `Wait-Reply` for the conversation.
+ * It refuses to start while any Chrome is still running on the profile,
+ * which would otherwise surface as a confusing startup failure.
+ */
+function headlessSessionLines(extraArgs) {
+    const quoted = extraArgs.map((arg) => `'${arg}'`).join(", ");
     return [
-        "param([string]$Chrome, [string]$Profile, [int]$StartupSeconds = 30)",
-        "$ErrorActionPreference = 'Stop'",
+        ...REFUSE_OPEN_PROFILE_LINES,
         "$portFile = Join-Path $Profile 'DevToolsActivePort'",
         "if (Test-Path $portFile) { Remove-Item $portFile -Force }",
-        "$args = @('--headless=new', '--no-first-run', '--no-default-browser-check', '--remote-debugging-port=0', \"--user-data-dir=$Profile\", 'about:blank')",
-        "$proc = Start-Process -FilePath $Chrome -ArgumentList $args -PassThru -WindowStyle Hidden",
+        `$chromeArgs = @('--headless=new', '--no-first-run', '--no-default-browser-check', ${quoted ? `${quoted}, ` : ""}'--remote-debugging-port=0', "--user-data-dir=\`"$Profile\`"", 'about:blank')`,
+        "$proc = Start-Process -FilePath $Chrome -ArgumentList $chromeArgs -PassThru -WindowStyle Hidden",
         "$deadline = (Get-Date).AddSeconds($StartupSeconds)",
-        "while (-not (Test-Path $portFile)) { if ((Get-Date) -gt $deadline) { throw 'Windows Chrome did not open its DevTools port in time.' }; if ($proc.HasExited) { throw 'Windows Chrome exited before opening its DevTools port.' }; Start-Sleep -Milliseconds 250 }",
+        "while (-not (Test-Path $portFile)) { if ((Get-Date) -gt $deadline) { throw 'Windows Chrome did not open its DevTools port in time.' }; if ($proc.HasExited) { throw 'Windows Chrome exited before opening its DevTools port; another Chrome may have opened on the sign-in profile.' }; Start-Sleep -Milliseconds 250 }",
         "Start-Sleep -Milliseconds 200",
         "$lines = Get-Content $portFile",
         "$port = [int]$lines[0]; $path = $lines[1]",
         "$ws = New-Object System.Net.WebSockets.ClientWebSocket",
-        "$cts = New-Object System.Threading.CancellationTokenSource 20000",
+        "$cts = New-Object System.Threading.CancellationTokenSource 30000",
         '$ws.ConnectAsync([Uri]("ws://127.0.0.1:$port$path"), $cts.Token).Wait()',
-        "function Send($obj) { $b = [Text.Encoding]::UTF8.GetBytes(($obj | ConvertTo-Json -Compress)); $ws.SendAsync([ArraySegment[byte]]$b, 'Text', $true, $cts.Token).Wait() }",
+        "function Send($obj) { $b = [Text.Encoding]::UTF8.GetBytes(($obj | ConvertTo-Json -Compress -Depth 6)); $ws.SendAsync([ArraySegment[byte]]$b, 'Text', $true, $cts.Token).Wait() }",
         "function Recv() { $buf = New-Object byte[] 65536; $ms = New-Object IO.MemoryStream; do { $r = $ws.ReceiveAsync([ArraySegment[byte]]$buf, $cts.Token).Result; $ms.Write($buf, 0, $r.Count) } while (-not $r.EndOfMessage); [Text.Encoding]::UTF8.GetString($ms.ToArray()) }",
+        "function Wait-Reply([int]$n) { while ($true) { $m = Recv; if ($m -match ('\"id\":' + $n + '[,}]')) { return $m } } }",
+    ];
+}
+/** PowerShell that closes the headless browser started by `headlessSessionLines`. */
+const CLOSE_HEADLESS_LINES = [
+    "try { Send @{ id = 0; method = 'Browser.close' } } catch {}",
+    "if (-not $proc.WaitForExit(10000)) { Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue }",
+];
+/**
+ * PowerShell that sets the profile's startup preference to "continue where
+ * you left off". Chrome deletes browser-session cookies (cookies with no
+ * expiry) when it exits normally unless that preference is set, and many
+ * sign-ins keep the signed-in state only in such cookies. With it set, the
+ * person can simply close the window and the sign-in survives for the
+ * harvest, and the next sign-in window reopens where they left off.
+ *
+ * The preference is protected against edits to the profile's files, so the
+ * script sets it the way the settings page does: it opens the profile
+ * headless, loads the settings page, and calls the settings API there. When
+ * the profile's preference files already show the value, Chrome is not
+ * started. The script prints `{"changed":bool,"value":n}`.
+ */
+export function keepSessionScript() {
+    return [
+        "param([string]$Chrome, [string]$Profile, [string]$Pattern, [int]$StartupSeconds = 30)",
+        "$ErrorActionPreference = 'Stop'",
+        ...REFUSE_OPEN_PROFILE_LINES,
+        "foreach ($name in @('Secure Preferences', 'Preferences')) { $prefsFile = Join-Path (Join-Path $Profile 'Default') $name; if (Test-Path $prefsFile) { try { $prefs = Get-Content -Raw $prefsFile | ConvertFrom-Json; if ($prefs.session.restore_on_startup -eq 1) { [Console]::Out.Write('{\"changed\":false,\"value\":1}'); exit 0 } } catch {} } }",
+        ...headlessSessionLines([]),
+        "Send @{ id = 1; method = 'Target.createTarget'; params = @{ url = 'chrome://settings/onStartup' } }",
+        "$targetId = (ConvertFrom-Json (Wait-Reply 1)).result.targetId",
+        "Send @{ id = 2; method = 'Target.attachToTarget'; params = @{ targetId = $targetId; flatten = $true } }",
+        "$sessionId = (ConvertFrom-Json (Wait-Reply 2)).result.sessionId",
+        "$expr = \"new Promise((resolve) => { const started = Date.now(); const attempt = () => { const api = globalThis.chrome && chrome.settingsPrivate; if (api) { api.setPref('session.restore_on_startup', 1, '', () => api.getPref('session.restore_on_startup', (pref) => resolve(JSON.stringify({ changed: true, value: pref ? pref.value : null })))); } else if (Date.now() - started > 10000) { resolve(JSON.stringify({ changed: false, value: null })); } else { setTimeout(attempt, 100); } }; attempt(); })\"",
+        "Send @{ id = 3; sessionId = $sessionId; method = 'Runtime.evaluate'; params = @{ expression = $expr; awaitPromise = $true; returnByValue = $true } }",
+        "$value = (ConvertFrom-Json (Wait-Reply 3)).result.result.value",
+        "Start-Sleep -Milliseconds 300",
+        ...CLOSE_HEADLESS_LINES,
+        "[Console]::Out.Write($value)",
+    ].join("\r\n");
+}
+/**
+ * PowerShell that does the whole read on the Windows side: start Chrome
+ * headless on the profile with its last session restored, read every cookie
+ * with `Storage.getCookies`, list the open pages with `Target.getTargets`,
+ * write both raw responses to stdout as one JSON object, and close the
+ * browser. WSL never touches the profile folder, which it may not be able to
+ * list. Every wait carries a deadline.
+ *
+ * Restoring the session keeps browser-session cookies that a forced stop left
+ * on disk, and it reopens the tabs the person had open, so the harvest can
+ * report the last page they reached on the sign-in site. That page's URL may
+ * carry a per-session token that cookies alone do not replace. The page list
+ * is polled for up to `$PageSeconds` until a page on `$Domain` appears.
+ */
+export function harvestScript() {
+    return [
+        "param([string]$Chrome, [string]$Profile, [string]$Pattern, [string]$Domain = '', [int]$StartupSeconds = 30, [int]$PageSeconds = 5)",
+        "$ErrorActionPreference = 'Stop'",
+        ...headlessSessionLines(["--restore-last-session"]),
+        "function Test-SiteUrl([string]$u) { if (-not $Domain) { return $false }; try { $h = ([Uri]$u).Host.ToLowerInvariant() } catch { return $false }; return ($h -eq $Domain -or $h.EndsWith('.' + $Domain)) }",
         "Send @{ id = 1; method = 'Storage.getCookies' }",
-        "$out = $null",
-        "while ($null -eq $out) { $m = Recv; if ($m -match '\"id\":1[,}]') { $out = $m } }",
-        "[Console]::Out.Write($out)",
-        "try { Send @{ id = 2; method = 'Browser.close' } } catch {}",
-        "if (-not $proc.WaitForExit(10000)) { Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue }",
+        "$cookiesReply = Wait-Reply 1",
+        "$pageDeadline = (Get-Date).AddSeconds($PageSeconds)",
+        "$n = 1",
+        "while ($true) { $n++; Send @{ id = $n; method = 'Target.getTargets' }; $targetsReply = Wait-Reply $n; $sitePages = @((ConvertFrom-Json $targetsReply).result.targetInfos | Where-Object { $_.type -eq 'page' -and (Test-SiteUrl $_.url) }); if ($sitePages.Count -gt 0 -or (Get-Date) -gt $pageDeadline) { break }; Start-Sleep -Milliseconds 250 }",
+        "[Console]::Out.Write('{\"cookies\":' + $cookiesReply + ',\"targets\":' + $targetsReply + '}')",
+        ...CLOSE_HEADLESS_LINES,
     ].join("\r\n");
 }
 /**
- * Reopen the Windows profile headless, read its cookies for `domain`, and
- * close it. Returns the cookies in the store's shape.
+ * URLs of the open pages on the sign-in site, in the order Chrome lists them,
+ * without duplicates.
  */
-export function harvestWindowsChromeCookies(input) {
+export function sitePages(targets, domain) {
+    const pages = [];
+    for (const target of targets) {
+        if (target.type !== "page")
+            continue;
+        let host;
+        try {
+            host = new URL(target.url).hostname;
+        }
+        catch {
+            continue;
+        }
+        if (host && cookieInDomain(host, domain) && !pages.includes(target.url))
+            pages.push(target.url);
+    }
+    return pages;
+}
+/** Parse the harvest script's stdout. */
+export function parseHarvestOutput(stdout, domain) {
+    const parsed = JSON.parse(stdout);
+    const cookieList = parsed.cookies?.result?.cookies;
+    if (!cookieList)
+        throw new Error(`Windows Chrome returned no cookie list: ${parsed.cookies?.error?.message ?? "unknown response"}`);
+    return {
+        cookies: cookiesForDomain(cookieList, domain),
+        pages: sitePages(parsed.targets?.result?.targetInfos ?? [], domain),
+    };
+}
+/** Write a PowerShell script to a temp file and run it with `-File`. */
+function runPowerShellScript(name, script, args, timeoutMs) {
     const scriptDir = join(tmpdir(), "harnery-windows-chrome");
     mkdirSync(scriptDir, { recursive: true });
-    const scriptLinux = join(scriptDir, `harvest-cookies-${process.pid}.ps1`);
-    writeFileSync(scriptLinux, harvestScript(), { mode: 0o600 });
+    const scriptLinux = join(scriptDir, `${name}-${process.pid}.ps1`);
+    writeFileSync(scriptLinux, script, { mode: 0o600 });
     try {
         const scriptWindows = spawnSync("wslpath", ["-w", scriptLinux], {
             encoding: "utf8",
         }).stdout.trim();
-        const result = spawnSync("powershell.exe", [
-            "-NoProfile",
-            "-ExecutionPolicy",
-            "Bypass",
-            "-File",
-            scriptWindows,
-            "-Chrome",
-            input.chromeWindows,
-            "-Profile",
-            input.profileWindows,
-            "-StartupSeconds",
-            String(input.startupTimeoutSeconds ?? 30),
-        ], { encoding: "utf8", timeout: 90_000, maxBuffer: 64 * 1024 * 1024 });
-        if (result.status !== 0) {
-            throw new Error(`Reading cookies from Windows Chrome failed: ${(result.stderr || result.stdout || "no output").trim().slice(0, 400)}`);
-        }
-        const parsed = JSON.parse(result.stdout);
-        if (!parsed.result?.cookies)
-            throw new Error(`Windows Chrome returned no cookie list: ${parsed.error?.message ?? "unknown response"}`);
-        return cookiesForDomain(parsed.result.cookies, input.domain);
+        const result = spawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptWindows, ...args], { encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            ...(result.error ? { error: result.error } : {}),
+        };
     }
     finally {
         rmSync(scriptLinux, { force: true });
     }
 }
 /**
- * Close any Chrome still running on `profileWindows`, for when the person ends
- * the sign-in from the terminal while the window is open. The profile must be
- * closed before its cookies can be read. Closing the window first lets Chrome
- * write recent cookies to disk; a forced stop is the fallback after 15 s.
+ * Reopen the Windows profile headless with its last session restored, read
+ * its cookies for `domain` and its open pages on that site, and close it.
+ * The profile must already be closed; see `stopWindowsChromeProfile`.
+ */
+export function harvestWindowsChromeCookies(input) {
+    const result = runPowerShellScript("harvest-cookies", harvestScript(), [
+        "-Chrome",
+        input.chromeWindows,
+        "-Profile",
+        input.profileWindows,
+        "-Pattern",
+        profileCommandLinePattern(input.profileWindows),
+        "-Domain",
+        input.domain,
+        "-StartupSeconds",
+        String(input.startupTimeoutSeconds ?? 30),
+        "-PageSeconds",
+        String(input.pageTimeoutSeconds ?? 5),
+    ], 90_000);
+    if (result.status !== 0) {
+        throw new Error(`Reading cookies from Windows Chrome failed: ${(result.stderr || result.stdout || result.error?.message || "no output").trim().slice(0, 400)}`);
+    }
+    return parseHarvestOutput(result.stdout, input.domain);
+}
+/**
+ * Set the profile to keep browser-session cookies across a normal exit; see
+ * `keepSessionScript`. Throws when Chrome is already open on the profile,
+ * since a second sign-in window would hand off to it. Any other failure
+ * returns `kept: false` so the caller can warn and continue.
  */
-export function stopWindowsChromeProfile(profileWindows) {
-    const escaped = profileWindows.replace(/'/g, "''");
-    const select = `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | Where-Object { $_.CommandLine -like '*${escaped}*' }`;
-    spawnSync("powershell.exe", [
-        "-NoProfile",
-        "-Command",
-        [
-            `$ids = @(${select} | ForEach-Object { $_.ProcessId })`,
-            "foreach ($id in $ids) { $p = Get-Process -Id $id -ErrorAction SilentlyContinue; if ($p -and $p.MainWindowHandle -ne 0) { [void]$p.CloseMainWindow() } }",
-            "$deadline = (Get-Date).AddSeconds(15)",
-            `while ((Get-Date) -lt $deadline -and @(${select}).Count -gt 0) { Start-Sleep -Milliseconds 250 }`,
-            `${select} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`,
-        ].join("; "),
-    ], { encoding: "utf8", timeout: 45_000 });
+export function keepWindowsChromeSession(input) {
+    const result = runPowerShellScript("keep-session", keepSessionScript(), [
+        "-Chrome",
+        input.chromeWindows,
+        "-Profile",
+        input.profileWindows,
+        "-Pattern",
+        profileCommandLinePattern(input.profileWindows),
+        "-StartupSeconds",
+        String(input.startupTimeoutSeconds ?? 30),
+    ], 90_000);
+    const detail = (result.stderr || result.stdout || result.error?.message || "").trim();
+    if (result.status !== 0) {
+        if (detail.includes("Chrome is still running on the sign-in profile"))
+            throw new Error(`Chrome is already open on the sign-in profile ${input.profileWindows}. Close that window and run the sign-in again.`);
+        return { kept: false, changed: false };
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return { kept: parsed.value === 1, changed: parsed.changed === true };
+    }
+    catch {
+        return { kept: false, changed: false };
+    }
+}
+/**
+ * PowerShell that closes every Chrome whose command line matches `$Pattern`. It asks each window to
+ * close, repeating so a profile with several windows closes them all, which
+ * lets Chrome write its cookies and session to disk. Whatever is still
+ * running after `$CloseSeconds` is stopped by force. The script prints
+ * `{found, forced, remaining}` as JSON; `remaining` lists process ids that
+ * survived even the forced stop.
+ */
+export function stopScript() {
+    return [
+        "param([string]$Pattern, [int]$CloseSeconds = 15)",
+        "$ErrorActionPreference = 'Stop'",
+        PROFILE_PROCESS_FUNCTION,
+        "$found = (Get-ProfileChrome).Count",
+        "$deadline = (Get-Date).AddSeconds($CloseSeconds)",
+        "while ($true) { $procs = Get-ProfileChrome; if ($procs.Count -eq 0 -or (Get-Date) -gt $deadline) { break }; foreach ($c in $procs) { try { $p = Get-Process -Id $c.ProcessId -ErrorAction SilentlyContinue; if ($p -and $p.MainWindowHandle -ne 0) { [void]$p.CloseMainWindow() } } catch {} }; Start-Sleep -Milliseconds 500 }",
+        "$forced = 0",
+        "foreach ($c in $(Get-ProfileChrome)) { Stop-Process -Id $c.ProcessId -Force -ErrorAction SilentlyContinue; $forced++ }",
+        "if ($forced -gt 0) { $killDeadline = (Get-Date).AddSeconds(10); while ((Get-ProfileChrome).Count -gt 0 -and (Get-Date) -lt $killDeadline) { Start-Sleep -Milliseconds 250 } }",
+        "$remaining = @(Get-ProfileChrome | ForEach-Object { [int]$_.ProcessId })",
+        "[Console]::Out.Write((@{ found = $found; forced = $forced; remaining = $remaining } | ConvertTo-Json -Compress))",
+    ].join("\r\n");
+}
+/** Parse the stop script's stdout; throws when a process survived. */
+export function parseStopOutput(stdout, profileWindows) {
+    const parsed = JSON.parse(stdout);
+    const remaining = parsed.remaining === undefined || parsed.remaining === null
+        ? []
+        : Array.isArray(parsed.remaining)
+            ? parsed.remaining
+            : [parsed.remaining];
+    if (remaining.length > 0) {
+        throw new Error(`Chrome is still running on ${profileWindows} (process ${remaining.join(", ")}) after a forced stop; its cookies cannot be read until it exits.`);
+    }
+    return { found: Number(parsed.found ?? 0), forced: Number(parsed.forced ?? 0) };
+}
+/**
+ * Close every Chrome still running on `profileWindows`, for when the person
+ * ends the sign-in from the terminal while the window is open. The profile
+ * must be closed before its cookies can be read. Closing the windows lets
+ * Chrome write recent cookies to disk; a forced stop is the fallback after
+ * `closeSeconds`, and it can lose cookies Chrome had not yet written. Throws
+ * when the stop cannot be confirmed, so the harvest never runs against a
+ * profile that is still open.
+ */
+export function stopWindowsChromeProfile(profileWindows, closeSeconds = 15) {
+    const result = runPowerShellScript("stop-profile", stopScript(), ["-Pattern", profileCommandLinePattern(profileWindows), "-CloseSeconds", String(closeSeconds)], (closeSeconds + 60) * 1000);
+    if (result.status !== 0) {
+        throw new Error(`Closing Chrome on ${profileWindows} failed: ${(result.stderr || result.stdout || result.error?.message || "no output").trim().slice(0, 400)}`);
+    }
+    return parseStopOutput(result.stdout, profileWindows);
 }
 /** Windows form of a `/mnt/<drive>/...` path. */
 export function wslPathToWindows(linuxPath) {

package/dist/lib/docs-links.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-links.d.ts","sourceRoot":"","sources":["../../src/lib/docs-links.ts"],"names":[],"mappings":"AAsCA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEhG,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAgGD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA2BlD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAoED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CA+B5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAuD3D;AA2CD,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACvC;AAED,UAAU,UAAU;IAClB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CA+HzD;AAiBD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAyClE"}
+{"version":3,"file":"docs-links.d.ts","sourceRoot":"","sources":["../../src/lib/docs-links.ts"],"names":[],"mappings":"AAsCA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEhG,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAgGD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA2BlD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAoED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CA+B5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM/C;AAgDD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAwD3D;AA2CD,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACvC;AAED,UAAU,UAAU;IAClB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CA+HzD;AAiBD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAyClE"}

package/dist/lib/docs-links.js

@@ -294,6 +294,48 @@ export function slugify(heading) {
         .replace(/[^\p{L}\p{N}\s_-]/gu, "")
         .replace(/\s/g, "-");
 }
+/** Keep literal code text out of the heading's inline-markup replacements. */
+function shieldHeadingCode(text) {
+    let marker = "\u0000";
+    while (text.includes(marker))
+        marker += "\u0000";
+    const spans = [];
+    const tokens = /<[^>]+>|`+/g;
+    let masked = "";
+    let copiedThrough = 0;
+    for (let opening = tokens.exec(text); opening; opening = tokens.exec(text)) {
+        // An HTML tag starts before its attribute values; their backticks are not
+        // code delimiters. Escaped opening backticks are literal punctuation too.
+        if (!opening[0].startsWith("`"))
+            continue;
+        let backslashes = 0;
+        for (let i = opening.index - 1; i >= 0 && text[i] === "\\"; i--)
+            backslashes++;
+        if (backslashes % 2 !== 0)
+            continue;
+        const closingRuns = /`+/g;
+        closingRuns.lastIndex = opening.index + opening[0].length;
+        let closing = closingRuns.exec(text);
+        while (closing && closing[0].length !== opening[0].length) {
+            closing = closingRuns.exec(text);
+        }
+        if (!closing)
+            continue;
+        let code = text.slice(opening.index + opening[0].length, closing.index);
+        // Code spans remove one padding space at each end, except all-space spans.
+        if (code.startsWith(" ") && code.endsWith(" ") && /[^ ]/.test(code)) {
+            code = code.slice(1, -1);
+        }
+        masked += text.slice(copiedThrough, opening.index) + marker + spans.length + marker;
+        spans.push(code);
+        copiedThrough = closing.index + closing[0].length;
+        tokens.lastIndex = copiedThrough;
+    }
+    return {
+        text: masked + text.slice(copiedThrough),
+        restore: (filtered) => filtered.replace(new RegExp(`${marker}(\\d+)${marker}`, "g"), (_, index) => spans[Number(index)]),
+    };
+}
 /**
  * Every fragment a reader can legitimately target in one document: Markdown
  * heading slugs (ATX and Setext), explicit `{#custom-id}` suffixes, and HTML
@@ -318,7 +360,8 @@ export function collectAnchors(content) {
         // so only word-boundary underscores are markup. `_` counts as a word
         // character in JS regex, so \b sits exactly at the space-to-underscore
         // seam these delimiters occupy.
-        text = text
+        const code = shieldHeadingCode(text);
+        text = code.text
             // Backslash escapes render as the bare character, so `snake\_case`
             // must anchor exactly like `snake_case`. Unescape before the emphasis
             // strip or the escaped underscore gains a phantom word boundary.
@@ -327,7 +370,7 @@ export function collectAnchors(content) {
             .replace(/[*~`]/g, "")
             .replace(/\b_+|_+\b/g, "")
             .replace(/<[^>]+>/g, "");
-        const base = slugify(text);
+        const base = slugify(code.restore(text));
         if (!base)
             return;
         const n = seen.get(base) ?? 0;

package/dist/lib/guarded-remove.d.ts

@@ -11,6 +11,12 @@ export interface RemoveOptions {
     allowProtected?: string[];
     /** Directories whose own Git metadata and Harnery state may never be allowed (the live workspace). */
     liveRoots?: string[];
+    /** Command-layer validation of the current caller's ownership of this exact managed artifact root. */
+    assertOwnedArtifact?: (root: string) => void;
+    /** Inspection bound; values above 10,000 require verified ownership of the exact artifact root. */
+    entryLimit?: number;
+    /** Remove only verified-clean standalone clones inside the caller's owned artifact. */
+    cleanClone?: boolean;
 }
 export interface RemovalLink {
     path: string;
@@ -23,6 +29,7 @@ export interface RemovalReport {
     root: string;
     targets: string[];
     entries: number;
+    entry_limit: number;
     bytes: number;
     /** Protected paths removed because the caller named them with allowProtected. */
     protected: string[];

package/dist/lib/guarded-remove.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-remove.d.ts","sourceRoot":"","sources":["../../src/lib/guarded-remove.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAKD,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,aAAa,EACtB,WAAW,GAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAe,GAClD,aAAa,CAyJf"}
+{"version":3,"file":"guarded-remove.d.ts","sourceRoot":"","sources":["../../src/lib/guarded-remove.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,sGAAsG;IACtG,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAMD,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,aAAa,EACtB,WAAW,GAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAe,GAClD,aAAa,CA4Mf"}