@astralyn/sash 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.1.2] - 2026-09-08
+
+### Added
+
+- Add Windows login startup through `sash auto [on|off|status]` and the dashboard settings. Preserve the selected data directory and report stale or OS-disabled entries; bare `sash auto` reads status.
+- Record login startup attempts and failures in a private rotating log, readable with `sash logs --startup` even when settings are invalid.
+- Add a source development launcher with separate data and ports, plus a `build` command for the WebUI.
+- Reorder profile cards with a long press and drag or Alt + Up/Down. Persist the order across dashboard refreshes without changing the active profile or reloading Core.
+
+### Changed
+
+- Make the daemon the only application state writer. Replace offline mutation, maintenance handoff and coordinated profile/Core transactions with one in-memory mutation queue.
+- Store settings, profile metadata and selection in one atomic schema-2 `sash.json`; store profile sources as immutable `<id>/<revision>.yaml` files. No old-format or API migration is provided.
+- Separate saving from applying. Profile edits, selection, scheduled updates and network preferences stay saved until Apply or `sash restart`; failed application preserves saved edits.
+- Make `sash web` start management without Core, and make `sash restart` replace Core while retaining the daemon and browser sessions.
+- Narrow Core updates to executable/install metadata. First installs and updates always complete health verification immediately, including a temporary start when initially stopped; retain rollback files until verification and runtime restoration succeed.
+- Keep Vue, the existing WebUI and LXGW WenKai Lite font. Share Core controls, refresh Core resources independently by visible page, and retain caches and latency results across metadata edits.
+- Remove TUN product fields, non-Windows desktop integration, raw settings editing in the dashboard, configuration reload aliases, `sash upgrade` and `sash update --force`.
+
+### Fixed
+
+- Cancel pending downloads and configuration validation on stop/shutdown; prevent stale responses from changing a replacement runtime.
+- Wrap long proxy node names across the full card width and keep latency controls on the metadata row.
+- Make profile card padding and unused space clickable while keeping rename, edit, update and delete actions independent.
+
+## [0.1.1] - 2026-09-08
+
+### Fixed
+
+- Start a stopped Core update from its already validated configuration before normal profile publication, preserving coordinated rollback until the health check succeeds. This also fixes first startup after installing Core with `sash update`.
+- Authorize dashboard HTTP and WebSocket control through private, single-use browser handoffs; keep credentials out of public health responses and preserve sessions across page refreshes.
+- Keep the recovery dashboard available when Core startup fails without authorizing competing starts from unknown runtime observations.
+- Fix native Windows log watching, clean font builds, temporary-directory aliases, private browser-handoff file checks and cross-platform test timing.
+- Retry ownership-safe system-proxy cleanup when an explicit disable request repeats the saved off state.
+- Preserve original transaction errors after successful rollback, retain causes on incomplete rollback and report stale settings snapshots as conflicts.
+
+### Added
+
+- Publish verified npm artifacts through GitHub Actions trusted publishing, with provenance and registry-install checks.
+- Add an npm release runbook, external package smoke checks and dependency update configuration.
+
+### Changed
+
+- Defer TUN and Windows Service Mode to the `feat/tun-service-mode` development branch. This release provides local HTTP/SOCKS endpoints and system-proxy controls, with no TUN or service administration controls.
+- Migrate enabled legacy TUN settings to off, reject new enable requests and explicitly disable TUN in generated configurations. Preserve original profile files and DNS/provider options; reject separate TUN listeners before publication.
+
 ## [0.1.0] - 2026-09-05
 
 ### Added

package/README.md

@@ -2,25 +2,25 @@
 
 > A lightweight command-line companion and web dashboard for a rule-based network core.
 
-Sash is a **network toolbox for developers and advanced users**. It installs, runs, and maintains a rule-based network core on your machine: local HTTP/SOCKS endpoints, rule-driven traffic routing, remote profile management, live traffic inspection through a built-in web dashboard, and an optional TUN mode for device-level traffic takeover.
+Sash is a **network toolbox for developers, learning, and research**. It installs, runs, and maintains a rule-based network core on your machine: local HTTP/SOCKS endpoints, rule-driven traffic routing, remote profile management, and live traffic inspection through a built-in web dashboard.
 
 ## Features
 
 - **Supervisor daemon (`sashd`)** — background supervisor on port `19090` managing the core lifecycle, recovery, and reverse proxying
 - **Zero-download web dashboard** — built-in modern Vue 3 dashboard bundled with the package at `http://127.0.0.1:19090/ui/`
-- **Reversible system proxy ownership** — snapshots and conditionally restores prior Windows, macOS, or GNOME proxy/PAC state after stop or crash
+- **Windows system proxy** — snapshots and conditionally restores the current user's prior proxy/PAC settings
 - **One-command lifecycle** — `sash start`, `stop`, `restart`, `status`, `logs`
-- **Remote profiles** — fetch, validate, schedule, and hot-reload core-format network profiles from the dashboard
+- **Windows login startup** — configure it through `sash auto on/off` or the dashboard settings
+- **Explicit save and apply** — import, edit and update profiles, then apply saved changes with one Core restart
 - **Verified upgrades** — SHA-256-verified downloads, bounded extraction, exact-version checks and atomic rollback (`sash update`)
-- **TUN mode** — device-level traffic takeover (requires starting the whole Sash runtime with elevated privileges)
 - **Credential hygiene** — child processes run with scrubbed environments; loopback traffic never traverses proxy dispatchers
 
 ## Requirements
 
 - Node.js **24 or newer**
-- Windows 10+, macOS, or Linux — x64 and arm64
+- Windows 10+ — x64 and arm64
 
-Automatic Linux system-proxy integration currently requires a GNOME desktop with `gsettings`; Core lifecycle and local endpoints do not have that desktop requirement.
+Basic Core lifecycle and local endpoints remain portable to macOS and Linux. Desktop system-proxy and login-startup integration are Windows-only.
 
 ## Install
 
@@ -49,11 +49,26 @@ sash status                # runtime state, endpoints, and proxy status
 sash stop                  # restores prior proxy state, stops core and sashd
 ```
 
+Use `sash web` to authorize and open the dashboard. Opening its address directly shows connection instructions. Refreshing an authorized tab preserves access; after restarting Sash, run `sash web` again.
+
+`sash web` also works while Core is stopped or missing. Profile selection, content edits and network settings are saved first; **Apply configuration** (or `sash restart`) restarts Core with those changes. Core updates and restarts keep the dashboard session alive.
+
+Use `sash auto on` to start Sash at login, `sash auto status` to inspect the
+registration and `sash auto off` to remove it. This requires a direct global npm
+installation and preserves the current data directory. See [Automatic Startup](./docs/autostart.md)
+for platform behavior, diagnostics and removal before uninstalling.
+
+TUN and Windows Service Mode remain on the [development branch](https://github.com/ming-kang/Sash/tree/feat/tun-service-mode). This branch keeps TUN disabled and runs without a privileged service.
+
+This refactor introduces a new state format and API without migration support. Use a fresh data directory and import any profile YAML you want to keep; existing state is never silently overwritten.
+
 ## Documentation
 
 Comprehensive documentation is available in the [`docs/`](./docs) directory:
 
-- [**User & Operations Guide**](./docs/usage.md) — complete CLI command reference, configuration parameters, TUN mode, and troubleshooting.
+- [**User & Operations Guide**](./docs/usage.md) — complete CLI command reference, configuration parameters and troubleshooting.
+- [**High-level Architecture**](./docs/architecture-proposal.md) — the implemented design, ownership boundaries and save/apply flow.
+- [**Automatic Startup**](./docs/autostart.md) — login startup, OS registration state and failure diagnostics.
 - [**Backend Architecture**](./docs/backend.md) — supervisor daemon model (`sashd`), API endpoints, lifecycle management, system proxy adapters, and safety invariants.
 - [**Frontend Architecture**](./docs/frontend.md) — built-in Vue 3 + Vite dashboard, shared API contracts, reactive runtime state, and WebSocket streaming.
 - [**Third-Party Notices**](./THIRD_PARTY_NOTICES.md) — licenses and attribution for code/assets embedded in the dashboard and the runtime-downloaded Core.

package/THIRD_PARTY_NOTICES.md

@@ -29,6 +29,15 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+## SortableJS
+
+- Package: `sortablejs` 1.15.7
+- Project: <https://github.com/SortableJS/Sortable>
+- License: MIT (permission and warranty terms reproduced above)
+- Copyright: Copyright (c) 2019 All contributors to Sortable
+
+The profile page embeds SortableJS for mouse and touch drag ordering.
+
 ## Remix Icon
 
 - Package: `@remixicon/vue` 4.9.0

package/dist/api.js

@@ -36,8 +36,11 @@ export class MihomoApi {
             return false;
         }
     }
-    async version() {
-        const res = await this.request("/version", { deadlineMs: 5_000, attempts: 2 });
+    async version(options = {}) {
+        const res = await this.request("/version", {
+            deadlineMs: options.deadlineMs ?? 5_000,
+            attempts: options.attempts ?? 2,
+        });
         if (res.statusCode < 200 || res.statusCode >= 300) {
             const summary = (await res.text(ERROR_BODY_LIMIT)).slice(0, 200).trim();
             throw new Error(`Mihomo API returned HTTP ${res.statusCode}: ${summary}`);
@@ -54,50 +57,16 @@ export class MihomoApi {
             return data.version.trim();
         throw new Error("Mihomo /version response is missing a non-empty version");
     }
-    async getTunActive() {
-        const res = await this.request("/configs", { deadlineMs: 2_000, attempts: 1 });
-        if (res.statusCode < 200 || res.statusCode >= 300) {
-            const summary = (await res.text(ERROR_BODY_LIMIT)).slice(0, 200).trim();
-            throw new Error(`Mihomo API returned HTTP ${res.statusCode}: ${summary}`);
-        }
-        const text = await res.text(1024 * 1024);
-        let data;
-        try {
-            data = JSON.parse(text);
-        }
-        catch {
-            throw new Error(`Invalid JSON response from Mihomo /configs: ${text.slice(0, 200).trim()}`);
-        }
-        if (typeof data !== "object" || data === null || Array.isArray(data)) {
-            throw new Error("Mihomo /configs response is not an object");
-        }
-        const tun = data.tun;
-        if (typeof tun !== "object" || tun === null || Array.isArray(tun)) {
-            throw new Error("Mihomo /configs response is missing the TUN runtime state");
-        }
-        const enable = tun.enable;
-        if (typeof enable !== "boolean") {
-            throw new Error("Mihomo /configs response is missing boolean tun.enable");
-        }
-        return enable;
-    }
-    async reloadConfig(configPath) {
-        const body = JSON.stringify({ path: configPath });
-        const res = await this.request("/configs?force=true", {
-            method: "PUT",
-            body,
-            deadlineMs: 5_000,
+    async setMode(mode) {
+        const response = await this.request("/configs", {
+            method: "PATCH",
+            body: JSON.stringify({ mode }),
+            attempts: 1,
         });
-        if (res.statusCode < 200 || res.statusCode >= 300) {
-            let bodyText = "";
-            try {
-                bodyText = (await res.text(ERROR_BODY_LIMIT)).trim();
-            }
-            catch {
-            }
-            const summary = bodyText ? `: ${bodyText.slice(0, 300)}` : "";
-            throw new Error(`Failed to reload Mihomo config (HTTP ${res.statusCode})${summary}`);
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+            const message = await response.text(ERROR_BODY_LIMIT);
+            throw new Error(`Core rejected mode change: HTTP ${response.statusCode}: ${message.slice(0, 200)}`);
         }
-        await res.discard();
+        await response.discard();
     }
 }

package/dist/app-state.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import { atomicWriteFileSync } from "./fs-atomic.js";
+import { hasExactOwnKeys, isPlainObject } from "./json-shape.js";
+import { sashLayout } from "./paths.js";
+import { parseProfilesIndex } from "./profile-model.js";
+import { DEFAULT_SETTINGS, initialSettings, validateSettingsCandidate, } from "./settings.js";
+const MAX_STATE_BYTES = 2 * 1024 * 1024;
+export class StateConflictError extends Error {
+}
+function readStateText(layout) {
+    try {
+        const stat = fs.lstatSync(layout.settingsFile);
+        if (!stat.isFile() || stat.size > MAX_STATE_BYTES)
+            throw new Error("Sash state must be a bounded regular file");
+        const bytes = fs.readFileSync(layout.settingsFile);
+        if (bytes.length > MAX_STATE_BYTES)
+            throw new Error("Sash state is too large");
+        return bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export function parseState(value) {
+    if (!isPlainObject(value) || value.schemaVersion !== 2) {
+        throw new Error("Invalid Sash state: schemaVersion must be 2");
+    }
+    if (!hasExactOwnKeys(value, ["schemaVersion", "revision", "settings", "profiles"]) ||
+        typeof value.revision !== "number" ||
+        !Number.isSafeInteger(value.revision) ||
+        value.revision < 0) {
+        throw new Error("Sash state has an invalid shape or revision");
+    }
+    return {
+        schemaVersion: 2,
+        revision: value.revision,
+        settings: validateSettingsCandidate(value.settings),
+        profiles: parseProfilesIndex(value.profiles),
+    };
+}
+function parseStateText(text, layout) {
+    try {
+        return parseState(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error(`Cannot read Sash state at ${layout.settingsFile}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+export function readState(layout = sashLayout()) {
+    const text = readStateText(layout);
+    return text === undefined ? undefined : parseStateText(text, layout);
+}
+export function loadSettings(layout = sashLayout()) {
+    return readState(layout)?.settings ?? { ...DEFAULT_SETTINGS };
+}
+export class SashStateStore {
+    layout;
+    state;
+    text;
+    constructor(layout, settings) {
+        this.layout = layout;
+        const stored = readStateText(layout);
+        if (stored !== undefined) {
+            this.state = parseStateText(stored, layout);
+            this.text = stored;
+        }
+        else {
+            this.state = {
+                schemaVersion: 2,
+                revision: 0,
+                settings: validateSettingsCandidate(settings ?? initialSettings()),
+                profiles: { activeId: null, profiles: [] },
+            };
+            this.text = `${JSON.stringify(this.state, null, 2)}\n`;
+            atomicWriteFileSync(layout.settingsFile, this.text);
+        }
+    }
+    snapshot() {
+        return structuredClone(this.state);
+    }
+    assertCurrent(revision) {
+        if (revision !== this.state.revision || readStateText(this.layout) !== this.text) {
+            throw new StateConflictError("Sash state changed; refresh before retrying. Edit files only while Sash is stopped.");
+        }
+    }
+    commit(candidate) {
+        this.assertCurrent(candidate.revision);
+        const next = parseState({ ...candidate, revision: candidate.revision + 1 });
+        const text = `${JSON.stringify(next, null, 2)}\n`;
+        if (Buffer.byteLength(text) > MAX_STATE_BYTES)
+            throw new Error("Sash state is too large");
+        atomicWriteFileSync(this.layout.settingsFile, text);
+        this.state = next;
+        this.text = text;
+        return this.snapshot();
+    }
+}

package/dist/autostart/command.js

@@ -0,0 +1,24 @@
+import { execFile } from "node:child_process";
+import { buildSanitizedEnv } from "../process.js";
+export const runAutostartCommand = (command, args, env) => new Promise((resolve, reject) => {
+    const child = execFile(command, args, {
+        encoding: "utf8",
+        env: buildSanitizedEnv(env),
+        timeout: 10_000,
+        maxBuffer: 256 * 1024,
+        windowsHide: true,
+        shell: false,
+    }, (error, stdout, stderr) => {
+        if (error && typeof error.code !== "number")
+            reject(error);
+        else
+            resolve({ code: typeof error?.code === "number" ? error.code : 0, stdout, stderr });
+    });
+    child.stdin?.end();
+});
+export function requireCommandSuccess(result) {
+    if (result.code !== 0) {
+        throw new Error("Autostart command failed: " +
+            (result.stderr.trim() || result.stdout.trim() || `exit code ${result.code}`).slice(0, 1000));
+    }
+}

package/dist/autostart/context.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { sashLayout } from "../paths.js";
+import { buildSanitizedEnv } from "../process.js";
+import { runAutostartCommand } from "./command.js";
+function absoluteEnvPath(value, fallback) {
+    const configured = value?.trim();
+    return configured && path.isAbsolute(configured) ? configured : fallback;
+}
+export function autostartContext(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const homedir = options.homedir ?? os.homedir();
+    const env = buildSanitizedEnv(options.env ?? process.env);
+    const packageRoot = options.packageRoot ?? path.resolve(import.meta.dirname, "../..");
+    const controlDir = path.join(absoluteEnvPath(env.LOCALAPPDATA, path.join(homedir, "AppData", "Local")), "Sash", "autostart");
+    const runCommand = options.runCommand ?? runAutostartCommand;
+    return {
+        platform,
+        homedir,
+        controlDir,
+        dataDir: path.resolve((options.layout ?? sashLayout()).root),
+        packageRoot,
+        nodePath: options.nodePath ?? process.execPath,
+        entryPath: path.join(packageRoot, "dist", "autostart-entry.js"),
+        env,
+        run: (command, args, extraEnv) => runCommand(command, args, buildSanitizedEnv({ ...env, ...extraEnv })),
+    };
+}
+export function assertLauncherValue(value) {
+    if (!value ||
+        Array.from(value).some((char) => char.charCodeAt(0) <= 31 || char.charCodeAt(0) === 127)) {
+        throw new Error("Autostart paths must be nonempty and contain no control characters");
+    }
+}
+export function launcherFilesExist(ctx) {
+    try {
+        return [ctx.nodePath, ctx.entryPath].every((file) => fs.statSync(file).isFile());
+    }
+    catch {
+        return false;
+    }
+}

package/dist/autostart/files.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import { errnoCode, errorMessage } from "../error-utils.js";
+import { atomicWriteFileSync, durableRemoveFileSync } from "../fs-atomic.js";
+export function readRegistration(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.size > 64 * 1024) {
+            throw new Error(`Invalid autostart registration file: ${file}`);
+        }
+        const flags = fs.constants.O_RDONLY | (process.platform === "win32" ? 0 : fs.constants.O_NOFOLLOW);
+        const fd = fs.openSync(file, flags);
+        try {
+            const opened = fs.fstatSync(fd);
+            if (!opened.isFile() || opened.size > 64 * 1024 || opened.ino !== stat.ino) {
+                throw new Error(`Autostart registration changed while reading: ${file}`);
+            }
+            const data = Buffer.alloc(64 * 1024 + 1);
+            const length = fs.readSync(fd, data, 0, data.length, 0);
+            if (length > 64 * 1024)
+                throw new Error(`Autostart registration is too large: ${file}`);
+            return data.subarray(0, length);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function registerFile(file, contents, register, compensate) {
+    const before = readRegistration(file);
+    const next = Buffer.from(contents);
+    atomicWriteFileSync(file, next);
+    try {
+        await register();
+    }
+    catch (error) {
+        try {
+            if (!readRegistration(file)?.equals(next)) {
+                throw new Error("Autostart launcher changed during registration; preserved it");
+            }
+            if (before)
+                atomicWriteFileSync(file, before);
+            else
+                durableRemoveFileSync(file);
+            await compensate?.();
+        }
+        catch (rollbackError) {
+            throw new Error(`${errorMessage(error)}; autostart rollback failed: ${errorMessage(rollbackError)}`, { cause: error });
+        }
+        throw error;
+    }
+}
+export function removeRegistration(file) {
+    if (readRegistration(file) !== undefined)
+        durableRemoveFileSync(file);
+}

package/dist/autostart/installation.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertLauncherValue } from "./context.js";
+const INSTALL_HINT = "Autostart requires a direct global installation. Install with npm install -g @astralyn/sash.";
+export function installationIssue(ctx) {
+    try {
+        for (const value of [ctx.nodePath, ctx.entryPath, ctx.dataDir])
+            assertLauncherValue(value);
+        if (!path.isAbsolute(ctx.nodePath) || !path.isAbsolute(ctx.entryPath))
+            return INSTALL_HINT;
+        const parts = path.resolve(ctx.packageRoot).replaceAll("\\", "/").toLowerCase().split("/");
+        if (parts.some((part) => ["_npx", ".pnpm", ".yarn", ".bun"].includes(part)))
+            return INSTALL_HINT;
+        const scope = path.dirname(ctx.packageRoot);
+        const modules = path.dirname(scope);
+        if (path.basename(ctx.packageRoot).toLowerCase() !== "sash" ||
+            path.basename(scope) !== "@astralyn" ||
+            path.basename(modules).toLowerCase() !== "node_modules") {
+            return INSTALL_HINT;
+        }
+        for (const directory of [ctx.packageRoot, scope, modules]) {
+            if (!fs.lstatSync(directory).isDirectory())
+                return INSTALL_HINT;
+        }
+        const parent = path.dirname(modules);
+        const prefix = parent;
+        for (const marker of ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"]) {
+            if (fs.existsSync(path.join(prefix, marker)))
+                return INSTALL_HINT;
+        }
+        const cli = path.join(ctx.packageRoot, "dist", "cli.js");
+        for (const file of [ctx.nodePath, ctx.entryPath, cli]) {
+            if (!fs.statSync(file).isFile())
+                return INSTALL_HINT;
+        }
+        const shim = path.join(prefix, "sash.cmd");
+        const stat = fs.lstatSync(shim);
+        if (!stat.isFile() || stat.size > 64 * 1024)
+            return INSTALL_HINT;
+        const contents = fs.readFileSync(shim, "utf8").replaceAll("/", "\\").toLowerCase();
+        if (!contents.includes("node_modules\\@astralyn\\sash\\dist\\cli.js"))
+            return INSTALL_HINT;
+        return null;
+    }
+    catch {
+        return INSTALL_HINT;
+    }
+}

package/dist/autostart/start.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import { loadSettings } from "../app-state.js";
+import { errnoCode, errorMessage } from "../error-utils.js";
+import { durableRenameSync } from "../fs-atomic.js";
+import { sashLayout } from "../paths.js";
+import { withPrivateAppendLogFds } from "../process.js";
+import { ensureRunning } from "../runtime-owner.js";
+function recordStart(layout, message) {
+    try {
+        fs.mkdirSync(layout.logsDir, { recursive: true, mode: 0o700 });
+        let stat;
+        try {
+            stat = fs.lstatSync(layout.sashLogFile);
+        }
+        catch (error) {
+            if (errnoCode(error) !== "ENOENT")
+                throw error;
+        }
+        if (stat && !stat.isFile())
+            throw new Error("Startup log is not a regular file");
+        if (stat && stat.size >= 1024 * 1024) {
+            durableRenameSync(layout.sashLogFile, `${layout.sashLogFile}.1`);
+        }
+        const line = `${new Date().toISOString()} ${message.replace(/[\r\n\t]+/g, " ").slice(0, 2000)}\n`;
+        withPrivateAppendLogFds(layout.sashLogFile, layout.sashLogFile, ({ stdoutFd }) => {
+            fs.writeSync(stdoutFd, line);
+        });
+    }
+    catch (error) {
+        console.error(`[sash] Could not write startup log: ${errorMessage(error)}`);
+    }
+}
+export async function startAtLogin(layout = sashLayout(), start = async () => {
+    const { result } = await ensureRunning({ layout, settings: loadSettings(layout) });
+    return result;
+}) {
+    recordStart(layout, "login start requested");
+    try {
+        const result = await start();
+        recordStart(layout, `login start ok pid=${result.pid}`);
+        return result;
+    }
+    catch (error) {
+        recordStart(layout, `login start failed: ${errorMessage(error)}`);
+        throw error;
+    }
+}

package/dist/autostart/windows-registry.js

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { isPlainObject } from "../json-shape.js";
+import { findExecutableOnPath } from "../process.js";
+import { requireCommandSuccess } from "./command.js";
+const REGISTRY_SETUP = [
+    "$ErrorActionPreference = 'Stop';",
+    "$runPath = 'Software\\Microsoft\\Windows\\CurrentVersion\\Run';",
+    "$approvalPath = 'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StartupApproved\\Run';",
+    "$name = 'Sash';",
+];
+const INSPECT_SCRIPT = [
+    ...REGISTRY_SETUP,
+    "try {",
+    "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($runPath);",
+    "$value = if ($key) { $key.GetValue($name, $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) } else { $null };",
+    "$run = if ($null -eq $value) { $null } elseif ($key.GetValueKind($name) -eq [Microsoft.Win32.RegistryValueKind]::String) { [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$value)) } else { '' };",
+    "if ($key) { $key.Dispose() };",
+    "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($approvalPath);",
+    "$value = if ($key) { $key.GetValue($name) } else { $null };",
+    "$approval = if ($null -eq $value) { $null } elseif (($value -is [byte[]]) -and $value.Length -ge 12) { [Convert]::ToBase64String($value) } else { '' };",
+    "if ($key) { $key.Dispose() };",
+    "[Console]::Out.Write((ConvertTo-Json ([ordered]@{ run = $run; approval = $approval }) -Compress));",
+    "} catch { [Console]::Error.Write($_.Exception.Message); exit 1 }",
+].join(" ");
+const SET_SCRIPT = [
+    ...REGISTRY_SETUP,
+    "$runKey = $null; $approvalKey = $null; $captured = $false;",
+    "try {",
+    "if ($env:SASH_AUTOSTART_MODE -notin @('on', 'off')) { throw 'Invalid autostart mode' };",
+    "$runKey = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($runPath);",
+    "$approvalKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($approvalPath, $true);",
+    "$oldRun = $runKey.GetValue($name, $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames);",
+    "$oldRunKind = if ($null -ne $oldRun) { $runKey.GetValueKind($name) } else { $null };",
+    "$oldApproval = if ($approvalKey) { $approvalKey.GetValue($name) } else { $null };",
+    "$oldApprovalKind = if ($null -ne $oldApproval) { $approvalKey.GetValueKind($name) } else { $null };",
+    "$captured = $true;",
+    "if ($env:SASH_AUTOSTART_MODE -eq 'on') {",
+    "  $runKey.SetValue($name, $env:SASH_AUTOSTART_COMMAND, [Microsoft.Win32.RegistryValueKind]::String);",
+    "} else { $runKey.DeleteValue($name, $false) };",
+    "if ($approvalKey) { $approvalKey.DeleteValue($name, $false) };",
+    "} catch {",
+    "$failure = $_.Exception.Message;",
+    "if ($captured) { try {",
+    "  if ($null -eq $oldRun) { $runKey.DeleteValue($name, $false) } else { $runKey.SetValue($name, $oldRun, $oldRunKind) };",
+    "  if ($approvalKey) { if ($null -eq $oldApproval) { $approvalKey.DeleteValue($name, $false) } else { $approvalKey.SetValue($name, $oldApproval, $oldApprovalKind) } };",
+    "} catch { $failure += '; registry rollback failed: ' + $_.Exception.Message } };",
+    "[Console]::Error.Write($failure); exit 1;",
+    "} finally { if ($runKey) { $runKey.Dispose() }; if ($approvalKey) { $approvalKey.Dispose() } }",
+].join(" ");
+export function windowsSystemPath(ctx, executable) {
+    const root = ctx.env.SystemRoot?.trim() || ctx.env.WINDIR?.trim() || "C:\\Windows";
+    if (!path.isAbsolute(root))
+        throw new Error("Windows system directory must be absolute");
+    return path.join(root, "System32", executable);
+}
+async function runRegistryScript(ctx, script, env) {
+    const shell = findExecutableOnPath("pwsh.exe", ctx.env) ??
+        windowsSystemPath(ctx, path.join("WindowsPowerShell", "v1.0", "powershell.exe"));
+    const result = await ctx.run(shell, [
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(script, "utf16le").toString("base64"),
+    ], env);
+    requireCommandSuccess(result);
+    return result.stdout;
+}
+function nullableBase64(value) {
+    return (value === null ||
+        (typeof value === "string" && Buffer.from(value, "base64").toString("base64") === value));
+}
+export async function readWindowsRegistration(ctx) {
+    const value = JSON.parse(await runRegistryScript(ctx, INSPECT_SCRIPT));
+    if (!isPlainObject(value) || !nullableBase64(value.run) || !nullableBase64(value.approval)) {
+        throw new Error("Invalid Windows autostart registry response");
+    }
+    const approval = value.approval === null ? undefined : Buffer.from(value.approval, "base64");
+    return {
+        command: value.run === null ? null : Buffer.from(value.run, "base64").toString("utf8"),
+        disabled: approval !== undefined && (approval.length < 12 || ![2, 6].includes(approval[0] ?? 0)),
+    };
+}
+export async function setWindowsRegistration(ctx, command) {
+    await runRegistryScript(ctx, SET_SCRIPT, {
+        SASH_AUTOSTART_MODE: command === null ? "off" : "on",
+        SASH_AUTOSTART_COMMAND: command ?? "",
+    });
+}