prismcast 1.10.2 → 1.10.3

package/dist/upgrade/lifecycle.context.d.ts

@@ -0,0 +1,19 @@
+import type { UpgradeLifecycleContext } from "./lifecycle.ts";
+/**
+ * Builds the default UpgradeLifecycleContext from real runtime I/O.
+ *
+ * runCommand inherits the user's terminal so npm/brew output flows live; it captures only the exit outcome, not the captured stdio. spawnDetached launches a
+ * fully decoupled child process - detached, stdio ignored, windowsHide on - then unref's so the child can outlive the parent. The Windows handoff strategy is
+ * the sole caller; on POSIX the strategy never invokes it.
+ *
+ * serviceTaskName resolves to the documented PrismCast service identifier when running on Windows. It is the empty string on other platforms because the field
+ * is only consumed by the Windows handoff helper. We always send the identifier (rather than gating on isRunningAsService) because the helper itself probes
+ * Get-ScheduledTask for the running task and skips the stop/start steps cleanly when none is registered...the user may be running a global npm install of
+ * prismcast on Windows without having registered a service yet, and the upgrade flow must still work.
+ *
+ * upgradeLogPath sits inside the PrismCast data directory at `upgrade.log`. The helper appends timestamped lines and the upgrade command's captured stdout to
+ * this file; the user is told its location in the "handed-off" UpgradeStep so they can tail or read it.
+ *
+ * @returns An UpgradeLifecycleContext populated from the live process.
+ */
+export declare function createDefaultLifecycleContext(): UpgradeLifecycleContext;

package/dist/upgrade/lifecycle.context.js

@@ -0,0 +1,47 @@
+import { execSync, spawn } from "node:child_process";
+import { SERVICE_NAME } from "../identity.js";
+import { getDataDir } from "../config/paths.js";
+import path from "node:path";
+/**
+ * Builds the default UpgradeLifecycleContext from real runtime I/O.
+ *
+ * runCommand inherits the user's terminal so npm/brew output flows live; it captures only the exit outcome, not the captured stdio. spawnDetached launches a
+ * fully decoupled child process - detached, stdio ignored, windowsHide on - then unref's so the child can outlive the parent. The Windows handoff strategy is
+ * the sole caller; on POSIX the strategy never invokes it.
+ *
+ * serviceTaskName resolves to the documented PrismCast service identifier when running on Windows. It is the empty string on other platforms because the field
+ * is only consumed by the Windows handoff helper. We always send the identifier (rather than gating on isRunningAsService) because the helper itself probes
+ * Get-ScheduledTask for the running task and skips the stop/start steps cleanly when none is registered...the user may be running a global npm install of
+ * prismcast on Windows without having registered a service yet, and the upgrade flow must still work.
+ *
+ * upgradeLogPath sits inside the PrismCast data directory at `upgrade.log`. The helper appends timestamped lines and the upgrade command's captured stdout to
+ * this file; the user is told its location in the "handed-off" UpgradeStep so they can tail or read it.
+ *
+ * @returns An UpgradeLifecycleContext populated from the live process.
+ */
+export function createDefaultLifecycleContext() {
+    return {
+        parentPid: process.pid,
+        platform: process.platform,
+        runCommand: (cmd, options) => {
+            try {
+                execSync(cmd, { cwd: options.cwd, encoding: "utf-8", stdio: "inherit" });
+                return { success: true };
+            }
+            catch {
+                return { success: false };
+            }
+        },
+        serviceTaskName: (process.platform === "win32") ? SERVICE_NAME : "",
+        spawnDetached: (command, args) => {
+            const child = spawn(command, [...args], {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true
+            });
+            child.unref();
+        },
+        upgradeLogPath: path.join(getDataDir(), "upgrade.log")
+    };
+}
+//# sourceMappingURL=lifecycle.context.js.map

package/dist/upgrade/lifecycle.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.context.js","sourceRoot":"","sources":["../../src/upgrade/lifecycle.context.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B;IAE3C,OAAO;QAEL,SAAS,EAAE,OAAO,CAAC,GAAG;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,UAAU,EAAE,CAAC,GAAW,EAAE,OAAkC,EAAoB,EAAE;YAEhF,IAAI,CAAC;gBAEH,QAAQ,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;gBAEzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBAEP,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,eAAe,EAAE,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;QACnE,aAAa,EAAE,CAAC,OAAe,EAAE,IAAuB,EAAQ,EAAE;YAEhE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;gBAEtC,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,QAAQ;gBACf,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;YAEH,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;QACD,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,aAAa,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/upgrade/lifecycle.d.ts

@@ -0,0 +1,72 @@
+import type { InstallInfo } from "./detection.ts";
+/**
+ * Outcome of a single upgrade attempt. Discriminated union over `kind`. Consumers narrow on it to choose between "the upgrade ran in-process, here is the
+ * outcome" and "a detached helper is taking it from here, exit immediately and trust the helper to finish the job."
+ *
+ * The "handed-off" variant is structurally permissible only because the strategy that produced it has already spawned the helper before returning; the field
+ * `logPath` is the path the helper writes its progress to so the user has a place to look while the upgrade is running.
+ */
+export type UpgradeStep = {
+    readonly kind: "ran";
+    readonly success: boolean;
+} | {
+    readonly kind: "handed-off";
+    readonly logPath: string;
+};
+/**
+ * Result of running an upgrade subprocess. Mirrors the same-named type in commands.ts...the in-process strategy passes this through verbatim, so callers of
+ * either layer see the same shape. The success flag distinguishes ran-without-error from threw-or-exited-non-zero; the runner does not surface the actual
+ * error because the user sees subprocess stderr directly on the terminal.
+ */
+export interface UpgradeRunResult {
+    readonly success: boolean;
+}
+/**
+ * Runtime context the lifecycle strategies consume. Each field is one narrow capability some strategy needs. POSIX strategies use only `runCommand`; the
+ * Windows handoff strategy uses `parentPid`, `serviceTaskName`, `spawnDetached`, `upgradeLogPath`. Splitting them onto one struct keeps the adapter (and the
+ * test seam) a single object, even though no strategy uses every field.
+ */
+export interface UpgradeLifecycleContext {
+    readonly parentPid: number;
+    readonly platform: NodeJS.Platform;
+    readonly runCommand: (cmd: string, options: {
+        readonly cwd?: string;
+    }) => UpgradeRunResult;
+    readonly serviceTaskName: string;
+    readonly spawnDetached: (command: string, args: readonly string[]) => void;
+    readonly upgradeLogPath: string;
+}
+/**
+ * A platform-strategy record. The registry is a flat tuple of these; the dispatcher picks the first whose `platforms` list includes the current OS. Pure
+ * function over UpgradeLifecycleContext + InstallInfo; no state is owned by the strategy itself.
+ */
+export interface UpgradeLifecycleStrategy {
+    readonly id: string;
+    readonly platforms: readonly NodeJS.Platform[];
+    readonly perform: (ctx: UpgradeLifecycleContext, info: InstallInfo) => UpgradeStep;
+}
+/**
+ * The upgrade-lifecycle strategy registry. Same runtime data as STRATEGY_TUPLE; the public name carries the wide UpgradeLifecycleStrategy type so consumers
+ * and tests see one uniform shape. Adding a new platform-specific strategy is appending an entry to STRATEGY_TUPLE; the dispatcher and the adapter never
+ * change.
+ */
+export declare const UPGRADE_LIFECYCLES: readonly UpgradeLifecycleStrategy[];
+/**
+ * Selects the lifecycle strategy for a given platform. Falls back to the POSIX in-process strategy when no strategy lists the platform...this matches
+ * PrismCast's historical behavior for any Unix-like host that is not specifically called out and keeps the function total (no thrown error from a one-off
+ * platform name).
+ *
+ * @param platform - The OS platform identifier.
+ * @returns The matching strategy, or the POSIX default when no strategy serves the platform.
+ */
+export declare function selectLifecycle(platform: NodeJS.Platform): UpgradeLifecycleStrategy;
+/**
+ * Performs an upgrade by selecting the platform-appropriate strategy and invoking its `perform` callback. Pure dispatcher; all I/O happens inside the
+ * strategy's own callbacks (which themselves receive an UpgradeLifecycleContext that the adapter wires from real I/O). Tests inject context literals and
+ * exercise each strategy through this entry point.
+ *
+ * @param ctx - The lifecycle context.
+ * @param info - The detected install info.
+ * @returns The upgrade outcome.
+ */
+export declare function performUpgrade(ctx: UpgradeLifecycleContext, info: InstallInfo): UpgradeStep;

package/dist/upgrade/lifecycle.js

@@ -0,0 +1,176 @@
+/**
+ * The PowerShell helper that the Windows handoff strategy spawns. Reads four positional parameters: the parent process ID, the optional service task name
+ * (empty string when no service is registered), the upgrade command exactly as detection.ts produced it, and the optional working directory for npm-local
+ * installs (empty string for npm-global).
+ *
+ * Sequence:
+ *
+ *   1. Wait for the parent process to exit. Wait-Process with -ErrorAction SilentlyContinue tolerates the (theoretical) case where the parent has already exited
+ *      between us being spawned and this line running.
+ *   2. If a service task is registered AND running, disable it (so RestartOnFailure does not interfere) and stop it. Stop-ScheduledTask is non-blocking, so we
+ *      poll for the task to transition out of Running with a 30-second ceiling - the same poll pattern as service/generators.ts's WINDOWS_REGISTER_SCRIPT.
+ *   3. Run the upgrade command via cmd.exe /c so npm/brew shell-style command lines parse correctly. Output is captured for the log; the exit code is captured
+ *      so we can re-raise it as our own exit code at the very end.
+ *   4. If a service task is registered, re-enable it and start it. The re-enable is necessary because Disable-ScheduledTask persists across restarts; without
+ *      this step, the next reboot would silently leave the service disabled.
+ *   5. Exit with the upgrade's exit code so the helper's own exit reflects the upgrade outcome (visible in the log via $LASTEXITCODE).
+ *
+ * Logging is best-effort: a failed Out-File call (e.g., the directory does not exist) is swallowed by SilentlyContinue so the helper still completes its
+ * primary job. The log itself is the only user-facing artifact of the helper, and we surface its path back to commands.ts as part of the UpgradeStep.
+ */
+const WINDOWS_HANDOFF_SCRIPT = [
+    "param($ParentPid, $TaskName, $UpgradeCommand, $WorkingDir, $LogPath)",
+    "function Write-UpgradeLog($message) {",
+    "  $stamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'",
+    "  try { Add-Content -Path $LogPath -Value ('[' + $stamp + '] ' + $message) -Encoding utf8 -ErrorAction SilentlyContinue } catch {}",
+    "}",
+    "Write-UpgradeLog ('Helper started; waiting for parent PID ' + $ParentPid + ' to exit.')",
+    "try { Wait-Process -Id $ParentPid -ErrorAction SilentlyContinue } catch {}",
+    "Write-UpgradeLog 'Parent exited.'",
+    "if($TaskName) {",
+    "  $existing = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue",
+    "  if($existing) {",
+    "    Write-UpgradeLog ('Disabling and stopping task ' + $TaskName + '.')",
+    "    Disable-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "    Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "    $deadline = (Get-Date).AddSeconds(30)",
+    "    while((Get-Date) -lt $deadline) {",
+    "      $state = (Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue).State",
+    "      if(($null -eq $state) -or ($state -ne 'Running')) { break }",
+    "      Start-Sleep -Milliseconds 250",
+    "    }",
+    "    Write-UpgradeLog ('Task state after stop: ' + $state + '.')",
+    "  } else {",
+    "    Write-UpgradeLog 'No matching scheduled task found; skipping stop/start.'",
+    "  }",
+    "}",
+    "if($WorkingDir) { Set-Location -Path $WorkingDir }",
+    "Write-UpgradeLog ('Running upgrade command: ' + $UpgradeCommand)",
+    "$upgradeOutput = (& cmd.exe /c $UpgradeCommand 2>&1) | Out-String",
+    "$upgradeExit = $LASTEXITCODE",
+    "try { Add-Content -Path $LogPath -Value $upgradeOutput -Encoding utf8 -ErrorAction SilentlyContinue } catch {}",
+    "Write-UpgradeLog ('Upgrade exit code: ' + $upgradeExit + '.')",
+    "if($TaskName) {",
+    "  $existing = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue",
+    "  if($existing) {",
+    "    Write-UpgradeLog ('Re-enabling and starting task ' + $TaskName + '.')",
+    "    Enable-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "    Start-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "  }",
+    "}",
+    "Write-UpgradeLog 'Helper finished.'",
+    "exit $upgradeExit"
+].join("\n");
+/**
+ * Escapes a value for embedding inside a single-quoted PowerShell string. PowerShell's single-quoted strings are literal (no interpolation, no backslash
+ * escapes); the only character that requires escaping is the single quote itself, written as two consecutive single quotes. Mirrors the same helper in
+ * service/generators.ts so the two PowerShell-emitting modules agree on the one escape rule that matters.
+ *
+ * @param value - The value to escape.
+ * @returns The value with internal single quotes doubled.
+ */
+function escapeSingleQuoted(value) {
+    return value.replaceAll("'", "''");
+}
+/**
+ * Wraps a value in a PowerShell single-quoted literal.
+ * @param value - The value to quote.
+ * @returns The literal including its surrounding quotes.
+ */
+function powerShellLiteral(value) {
+    return "'" + escapeSingleQuoted(value) + "'";
+}
+/**
+ * Builds the PowerShell command string that the Windows handoff strategy passes to powershell.exe via -Command. The script body is wrapped in `& { ... }` and
+ * the positional arguments are appended after the closing brace, exactly as PowerShell's parser expects. Each argument is single-quote-escaped via
+ * powerShellLiteral, so there is one - and only one - escape surface (the single-quote doubling rule).
+ *
+ * @param args - The positional arguments to pass to the helper script's param() block, in declaration order.
+ * @returns The fully composed `-Command` string.
+ */
+function buildHandoffCommand(args) {
+    const quoted = args.map((value) => powerShellLiteral(value)).join(" ");
+    return "& { " + WINDOWS_HANDOFF_SCRIPT + " } " + quoted;
+}
+/**
+ * POSIX in-process strategy. macOS and Linux can run `npm install -g` (or `brew upgrade`) directly from inside the running prismcast process because POSIX
+ * filesystems do not lock open files against directory rename. The strategy is a thin pass-through over ctx.runCommand. The caller (commands.ts) decides
+ * whether to exit afterward so the service manager (launchd KeepAlive, systemd Restart=) brings PrismCast back up.
+ */
+const POSIX_IN_PROCESS_LIFECYCLE = {
+    id: "posix-in-process",
+    perform: (ctx, info) => {
+        const result = ctx.runCommand(info.upgradeCommand, { cwd: info.packageDir });
+        return { kind: "ran", success: result.success };
+    },
+    platforms: ["darwin", "linux"]
+};
+/**
+ * Windows handoff strategy. Composes the PowerShell helper command line, hands it to ctx.spawnDetached, and returns "handed-off." The helper waits for the
+ * current process to exit (so the prismcast directory's file locks release), runs the upgrade, then restarts the scheduled task if one exists. This is the
+ * Windows EBUSY + auto-restart fix: the parent process exits cleanly with an "upgrade running in the background" message; the detached helper handles the rest.
+ *
+ * The PowerShell launch is identical to the rest of the codebase: -NoProfile / -NonInteractive for a clean shell, -ExecutionPolicy Bypass so installer-style
+ * scripted scenarios are not gated by the interactive-use policy, -WindowStyle Hidden so the user sees no console window pop up, and -Command with our
+ * single-quote-escaped script string. The launcher is spawned detached, with stdio ignored and windowsHide set, so it survives the parent's exit.
+ */
+const WINDOWS_HANDOFF_LIFECYCLE = {
+    id: "windows-handoff",
+    perform: (ctx, info) => {
+        const handoffCommand = buildHandoffCommand([
+            String(ctx.parentPid),
+            ctx.serviceTaskName,
+            info.upgradeCommand,
+            info.packageDir ?? "",
+            ctx.upgradeLogPath
+        ]);
+        ctx.spawnDetached("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy", "Bypass",
+            "-WindowStyle", "Hidden",
+            "-Command", handoffCommand
+        ]);
+        return { kind: "handed-off", logPath: ctx.upgradeLogPath };
+    },
+    platforms: ["win32"]
+};
+/* The strategy registry as a narrow tuple. Declared `as const` so each entry retains its literal shape...the dispatcher walks this in order and picks the
+ * first match. POSIX comes first because it serves more platforms; Windows comes second because it serves only one. The default-fallback semantics live in
+ * performUpgrade so an unknown platform (e.g., freebsd) falls through to the POSIX strategy, which is the most permissive choice and matches PrismCast's
+ * historical pre-Windows behavior.
+ */
+const STRATEGY_TUPLE = [
+    POSIX_IN_PROCESS_LIFECYCLE,
+    WINDOWS_HANDOFF_LIFECYCLE
+];
+/**
+ * The upgrade-lifecycle strategy registry. Same runtime data as STRATEGY_TUPLE; the public name carries the wide UpgradeLifecycleStrategy type so consumers
+ * and tests see one uniform shape. Adding a new platform-specific strategy is appending an entry to STRATEGY_TUPLE; the dispatcher and the adapter never
+ * change.
+ */
+export const UPGRADE_LIFECYCLES = STRATEGY_TUPLE;
+/**
+ * Selects the lifecycle strategy for a given platform. Falls back to the POSIX in-process strategy when no strategy lists the platform...this matches
+ * PrismCast's historical behavior for any Unix-like host that is not specifically called out and keeps the function total (no thrown error from a one-off
+ * platform name).
+ *
+ * @param platform - The OS platform identifier.
+ * @returns The matching strategy, or the POSIX default when no strategy serves the platform.
+ */
+export function selectLifecycle(platform) {
+    return UPGRADE_LIFECYCLES.find((strategy) => strategy.platforms.includes(platform)) ?? POSIX_IN_PROCESS_LIFECYCLE;
+}
+/**
+ * Performs an upgrade by selecting the platform-appropriate strategy and invoking its `perform` callback. Pure dispatcher; all I/O happens inside the
+ * strategy's own callbacks (which themselves receive an UpgradeLifecycleContext that the adapter wires from real I/O). Tests inject context literals and
+ * exercise each strategy through this entry point.
+ *
+ * @param ctx - The lifecycle context.
+ * @param info - The detected install info.
+ * @returns The upgrade outcome.
+ */
+export function performUpgrade(ctx, info) {
+    return selectLifecycle(ctx.platform).perform(ctx, info);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/upgrade/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/upgrade/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/upgrade/pathHandle.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A platform-aware handle on an absolute filesystem path. Strategies reason about install layout exclusively through this type; the underlying separator,
+ * case-folding rules, and segment topology are encapsulated. Adding a new structural query is an additive edit to this interface; the factory below is the only
+ * implementation site.
+ */
+export interface PathHandle {
+    readonly raw: string;
+    hasSegmentChain(...segments: readonly string[]): boolean;
+    isUnder(prefix: string): boolean;
+    join(...segments: readonly string[]): string;
+    parentBefore(...segments: readonly string[]): PathHandle | null;
+}
+/**
+ * Options accepted by createPathHandle. Today there is only the platform override, used by tests to produce Windows-flavored handles on a Linux host.
+ */
+export interface PathHandleOptions {
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Constructs a PathHandle from an absolute path string. The factory captures the platform once and dispatches every subsequent query through `path.win32` or
+ * `path.posix` accordingly, so behavior is independent of where the host process runs. The handle is logically immutable...returned fields are typed readonly
+ * and the closed-over state is never mutated.
+ *
+ * @param raw - The OS-native absolute path string. Empty or relative inputs produce a degenerate handle whose query methods return false / null defensively.
+ * @param options - Optional overrides. Today only the platform override is supported.
+ * @returns A platform-aware PathHandle.
+ */
+export declare function createPathHandle(raw: string, options?: PathHandleOptions): PathHandle;

package/dist/upgrade/pathHandle.js

@@ -0,0 +1,101 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * pathHandle.ts: A narrow value type that wraps an absolute filesystem path with platform-aware structural query primitives. This module is the single source of
+ * truth for path semantics in the upgrade-detection layer - separator selection, case-folding rules, segment splitting, and prefix containment all live here. The
+ * detection strategies receive a PathHandle (not a raw string) and reason about install layout exclusively through its narrow API. By construction a strategy
+ * cannot write `currentFile.includes("/node_modules/")` and accidentally hard-code POSIX semantics into a cross-platform code path, because PathHandle has no
+ * `.includes` method...the only way to test for a "node_modules/prismcast" run in the path is `hasSegmentChain("node_modules", "prismcast")`, which dispatches to
+ * the right separator and case-folding rule automatically.
+ *
+ * The factory accepts an explicit platform override so cross-platform tests can produce Windows-flavored handles on a Linux CI host. Internally, the factory
+ * dispatches every path operation to `path.win32` or `path.posix` rather than the ambient `path` module, so behavior is deterministic regardless of where the
+ * host process runs. macOS is treated as case-sensitive, matching Node's `path.posix` semantics; APFS volumes with case-sensitive flags work correctly, and
+ * macOS users on default case-insensitive volumes are unaffected because `import.meta.url` and any subprocess output agree on canonical casing in the install
+ * layouts PrismCast targets.
+ *
+ * The API is deliberately small. `raw` is the lone escape hatch, used for handoff to subprocess cwd (the npm-local resolver's packageDir) and for display. Every
+ * other operation is a structural query or platform-aware composition, so strategy authors never need to reason about separators or case-folding rules.
+ */
+import path from "node:path";
+/**
+ * Constructs a PathHandle from an absolute path string. The factory captures the platform once and dispatches every subsequent query through `path.win32` or
+ * `path.posix` accordingly, so behavior is independent of where the host process runs. The handle is logically immutable...returned fields are typed readonly
+ * and the closed-over state is never mutated.
+ *
+ * @param raw - The OS-native absolute path string. Empty or relative inputs produce a degenerate handle whose query methods return false / null defensively.
+ * @param options - Optional overrides. Today only the platform override is supported.
+ * @returns A platform-aware PathHandle.
+ */
+export function createPathHandle(raw, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const isWindows = (platform === "win32");
+    const pathLib = isWindows ? path.win32 : path.posix;
+    // Case-folding rule. Windows is the only platform where the OS treats the filesystem as case-insensitive for path comparisons. POSIX (including macOS at the
+    // Node API layer) is case-sensitive. Folding both sides of every comparison consistently is sufficient; we do not need to canonicalize the raw path itself.
+    const fold = (segment) => isWindows ? segment.toLowerCase() : segment;
+    // Pre-computed segment lists. rawSegments preserves the original casing for path reconstruction (parentBefore needs to splice the original spelling back
+    // together so the resulting handle's raw path is byte-faithful to the input). normalized is the folded form used for every comparison.
+    const rawSegments = raw.split(pathLib.sep);
+    const normalized = rawSegments.map(fold);
+    // Locates the first index at which a normalized segment chain matches the path. Returns -1 when there is no match, and also when the chain is empty...we
+    // explicitly refuse the vacuous-truth case so an empty rest-parameter expansion never produces a surprising hit.
+    const findChain = (chain) => {
+        if (chain.length === 0) {
+            return -1;
+        }
+        const target = chain.map(fold);
+        const lastStart = normalized.length - target.length;
+        for (let i = 0; i <= lastStart; i++) {
+            if (target.every((segment, j) => normalized[i + j] === segment)) {
+                return i;
+            }
+        }
+        return -1;
+    };
+    return {
+        hasSegmentChain(...segments) {
+            return findChain(segments) !== -1;
+        },
+        isUnder(prefix) {
+            // Defensive guard. An empty or relative prefix is not anchorable in the install-detection sense...relative containment is undefined for absolute filesystem
+            // paths, and an empty prefix would trivially match every path, which is never useful here.
+            if (!prefix || !pathLib.isAbsolute(prefix)) {
+                return false;
+            }
+            // We compare segment lists rather than calling pathLib.relative because Node's relative() has implementation-defined case-handling on Windows that varies
+            // by version and is undocumented at the API surface. A hand-rolled split-and-compare gives us one explicit rule that we own and can test. Empty segments
+            // (which arise from leading separators on POSIX and the UNC double-leading on Windows) are filtered out symmetrically so the comparison is well-defined
+            // for every absolute layout we care about.
+            const prefixSegments = pathLib.normalize(prefix).split(pathLib.sep).map(fold).filter((segment) => segment.length > 0);
+            const haystack = normalized.filter((segment) => segment.length > 0);
+            if ((prefixSegments.length === 0) || (prefixSegments.length >= haystack.length)) {
+                return false;
+            }
+            for (let i = 0; i < prefixSegments.length; i++) {
+                if (haystack[i] !== prefixSegments[i]) {
+                    return false;
+                }
+            }
+            return true;
+        },
+        join(...segments) {
+            return pathLib.join(raw, ...segments);
+        },
+        parentBefore(...segments) {
+            const index = findChain(segments);
+            // index <= 0 means no match, or a match at position zero with no parent above it. Either way there is no meaningful parent path to return.
+            if (index <= 0) {
+                return null;
+            }
+            const parentRaw = rawSegments.slice(0, index).join(pathLib.sep);
+            // The reconstructed parent must be a meaningful absolute path. A bare Windows drive letter ("C:") or the POSIX root with no segments above the chain
+            // ("") fails this check and we return null...these are degenerate install layouts (prismcast at the filesystem root) that have no usable project root.
+            if (!pathLib.isAbsolute(parentRaw)) {
+                return null;
+            }
+            return createPathHandle(parentRaw, { platform });
+        },
+        raw
+    };
+}
+//# sourceMappingURL=pathHandle.js.map

package/dist/upgrade/pathHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathHandle.js","sourceRoot":"","sources":["../../src/upgrade/pathHandle.ts"],"names":[],"mappings":"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"}

package/dist/utils/bootSession.context.d.ts

@@ -0,0 +1,15 @@
+import type { BootSessionContext } from "./bootSession.ts";
+import type { Nullable } from "../types/index.ts";
+/**
+ * Builds the default BootSessionContext from real runtime I/O, snapshotting every reading at construction time so subsequent accessor calls return frozen values.
+ * @returns A BootSessionContext whose readings are frozen at the moment of this call.
+ */
+export declare function createDefaultBootSessionContext(): BootSessionContext;
+/**
+ * Parses field 22 (starttime) out of a /proc/<pid>/stat payload. The format embeds the executable name in parentheses at field 2; that name can itself contain
+ * whitespace and parentheses, so we anchor on the last closing paren before splitting the remainder on whitespace. The first field after the closing paren is
+ * field 3 (state), which makes the starttime we want land at index 19 of the post-paren split. Exported for direct unit testing.
+ * @param raw - The /proc/<pid>/stat payload as a string.
+ * @returns The starttime field as a string, or null when the payload is malformed.
+ */
+export declare function parsePid1StartTicks(raw: string): Nullable<string>;

package/dist/utils/bootSession.context.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import { isRunningInContainer } from "./platform.js";
+import os from "node:os";
+/**
+ * Builds the default BootSessionContext from real runtime I/O, snapshotting every reading at construction time so subsequent accessor calls return frozen values.
+ * @returns A BootSessionContext whose readings are frozen at the moment of this call.
+ */
+export function createDefaultBootSessionContext() {
+    // Snapshot the host boot minute by computing it from system uptime. os.uptime() is sleep-inclusive on Linux, macOS, and Windows (Node delegates to platform
+    // primitives that all include suspended time), so this value remains stable across sleep/wake cycles. Rounding to the nearest minute absorbs sub-minute NTP
+    // drift between writes and reads. Future upgrade: on Linux, /proc/sys/kernel/random/boot_id is a kernel-generated UUID that is regenerated each boot and
+    // immune to clock drift; switching this branch to read that file would eliminate the minute-boundary jitter entirely. macOS (sysctl kern.boottime) and
+    // Windows (Win32_OS.LastBootUpTime) have equivalent kernel facts but require a subprocess; deferred until a real boundary-jitter incident motivates the work.
+    const hostBootMinuteSnapshot = Math.round((Date.now() - (os.uptime() * 1000)) / 60000);
+    // Snapshot the container detection result. The project-wide helper reads PRISMCAST_CONTAINER and /.dockerenv; both are stable for the process lifetime.
+    const inContainerSnapshot = isRunningInContainer();
+    // Snapshot the container instance tag only when in a container. Outside a container /proc/1/stat is the host init, which would not distinguish container
+    // restarts within the same host boot; skipping the read avoids spurious work on macOS and Windows where /proc does not exist.
+    const containerInstanceTagSnapshot = inContainerSnapshot ? readPid1StartTicks() : null;
+    return {
+        containerInstanceTag: () => containerInstanceTagSnapshot,
+        hostBootMinute: () => hostBootMinuteSnapshot,
+        inContainer: () => inContainerSnapshot
+    };
+}
+/**
+ * Reads field 22 (starttime, clock ticks since boot) from /proc/1/stat. ENOENT on non-Linux platforms and any read failure resolve to null. The parsing is
+ * delegated to parsePid1StartTicks so it can be exercised in tests without an injectable filesystem.
+ * @returns The container init's starttime as a string, or null when /proc/1/stat is unavailable or malformed.
+ */
+function readPid1StartTicks() {
+    try {
+        return parsePid1StartTicks(fs.readFileSync("/proc/1/stat", "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parses field 22 (starttime) out of a /proc/<pid>/stat payload. The format embeds the executable name in parentheses at field 2; that name can itself contain
+ * whitespace and parentheses, so we anchor on the last closing paren before splitting the remainder on whitespace. The first field after the closing paren is
+ * field 3 (state), which makes the starttime we want land at index 19 of the post-paren split. Exported for direct unit testing.
+ * @param raw - The /proc/<pid>/stat payload as a string.
+ * @returns The starttime field as a string, or null when the payload is malformed.
+ */
+export function parsePid1StartTicks(raw) {
+    const rparen = raw.lastIndexOf(")");
+    if (rparen === -1) {
+        return null;
+    }
+    const fields = raw.slice(rparen + 1).trim().split(/\s+/);
+    if (fields.length < 20) {
+        return null;
+    }
+    // Coalesce to null even though the length guard above proves the index is in range; TypeScript's noUncheckedIndexedAccess still types fields[19] as
+    // string | undefined and the explicit ?? null keeps the return type honest.
+    return fields[19] ?? null;
+}
+//# sourceMappingURL=bootSession.context.js.map

package/dist/utils/bootSession.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootSession.context.js","sourceRoot":"","sources":["../../src/utils/bootSession.context.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB;;;GAGG;AACH,MAAM,UAAU,+BAA+B;IAE7C,4JAA4J;IAC5J,4JAA4J;IAC5J,yJAAyJ;IACzJ,uJAAuJ;IACvJ,8JAA8J;IAC9J,MAAM,sBAAsB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IAEvF,wJAAwJ;IACxJ,MAAM,mBAAmB,GAAG,oBAAoB,EAAE,CAAC;IAEnD,yJAAyJ;IACzJ,8HAA8H;IAC9H,MAAM,4BAA4B,GAAG,mBAAmB,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAEvF,OAAO;QAEL,oBAAoB,EAAE,GAAG,EAAE,CAAC,4BAA4B;QACxD,cAAc,EAAE,GAAG,EAAE,CAAC,sBAAsB;QAC5C,WAAW,EAAE,GAAG,EAAE,CAAC,mBAAmB;KACvC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB;IAEzB,IAAI,CAAC;QAEH,OAAO,mBAAmB,CAAC,EAAE,CAAC,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QAEP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAE7C,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAG,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAEjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAEzD,IAAG,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAEtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oJAAoJ;IACpJ,4EAA4E;IAC5E,OAAO,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC"}

package/dist/utils/bootSession.d.ts

@@ -0,0 +1,16 @@
+import type { Nullable } from "../types/index.ts";
+/**
+ * The runtime capability set getBootSessionId consumes. Production wires it from real I/O via createDefaultBootSessionContext; tests pass a context literal.
+ */
+export interface BootSessionContext {
+    readonly containerInstanceTag: () => Nullable<string>;
+    readonly hostBootMinute: () => number;
+    readonly inContainer: () => boolean;
+}
+/**
+ * Returns the boot session identifier for the current process. Outside a container the identifier is just the host boot minute; inside, it is composed with
+ * the container init's instance tag so each container restart yields a distinct value even within the same host boot.
+ * @param ctx - The boot session context. Defaults to a module-load snapshot of real runtime I/O.
+ * @returns A string that is stable across calls in the same kernel/container session and differs across reboots or container restarts.
+ */
+export declare function getBootSessionId(ctx?: BootSessionContext): string;

package/dist/utils/bootSession.js

@@ -0,0 +1,20 @@
+import { createDefaultBootSessionContext } from "./bootSession.context.js";
+/* The default context is created once at module load. createDefaultBootSessionContext() snapshots its readings, so this constant captures the boot identifier
+ * for the entire process lifetime. Tests bypass it by passing their own context literal.
+ */
+const defaultContext = createDefaultBootSessionContext();
+/**
+ * Returns the boot session identifier for the current process. Outside a container the identifier is just the host boot minute; inside, it is composed with
+ * the container init's instance tag so each container restart yields a distinct value even within the same host boot.
+ * @param ctx - The boot session context. Defaults to a module-load snapshot of real runtime I/O.
+ * @returns A string that is stable across calls in the same kernel/container session and differs across reboots or container restarts.
+ */
+export function getBootSessionId(ctx = defaultContext) {
+    const host = String(ctx.hostBootMinute());
+    if (!ctx.inContainer()) {
+        return host;
+    }
+    const tag = ctx.containerInstanceTag();
+    return (tag === null) ? host : (host + "::" + tag);
+}
+//# sourceMappingURL=bootSession.js.map

package/dist/utils/bootSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootSession.js","sourceRoot":"","sources":["../../src/utils/bootSession.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAkB3E;;GAEG;AACH,MAAM,cAAc,GAAG,+BAA+B,EAAE,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0B,cAAc;IAEvE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC;IAE1C,IAAG,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;QAEtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,CAAC,oBAAoB,EAAE,CAAC;IAEvC,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC;AACrD,CAAC"}

package/dist/utils/clock.js

@@ -5,7 +5,7 @@
  * default realClock delegates to delay() and raceWithTimeout() in delay.ts and to performance.now() in the runtime; tests pass a fake-clock literal that resolves
  * sleeps instantly and chooses raceWithTimeout outcomes explicitly.
  *
- * Why this exists. Node's built-in node:test mock.timers exposes only synchronous tick() and runAll() - it has never shipped a tickAsync/runAllAsync variant on
+ * Why this exists. Node's builtin node:test mock.timers exposes only synchronous tick() and runAll() - it has never shipped a tickAsync/runAllAsync variant on
  * any version. Synchronous tick advances the fake clock but does not drain microtask chains across nested Promise.race / .finally / await delay() patterns; the
  * promises stay pending past the tick. retryOperation is the canonical case: its internal raceWithTimeout -> Promise.race -> .finally -> await delay() chain is
  * exactly the shape mock.timers cannot deterministically resolve. Injecting a Clock sidesteps the runtime gap entirely - tests provide a sleep() that resolves

package/dist/utils/ffmpeg.js

@@ -198,7 +198,7 @@ function spawnFFmpegProcess({ args, ffmpegBin, label, onError, streamId }) {
 export function buildSpawnFFmpegArgs(audioBitrate, options = {}) {
     const platform = options.platform ?? process.platform;
     const comment = options.comment;
-    // Use Apple's AudioToolbox AAC encoder on macOS for better quality and performance. Fall back to FFmpeg's built-in AAC encoder on other platforms.
+    // Use Apple's AudioToolbox AAC encoder on macOS for better quality and performance. Fall back to FFmpeg's builtin AAC encoder on other platforms.
     const aacEncoder = platform === "darwin" ? "aac_at" : "aac";
     const ffmpegArgs = [
         ...FFMPEG_INPUT_FLAGS,