dsh-home-hosted 0.1.0

package/lib/types/boot/common.d.ts

@@ -0,0 +1,40 @@
+import type { BootState } from '../shared/contracts.js';
+import type { BootActionResult, BootProviderContext } from './types.js';
+export declare function errorMessage(error: unknown): string;
+/** Existence check through the injected seam, so a probe is testable without touching the host. */
+export declare function existsOf(ctx: BootProviderContext, file: string): boolean;
+export declare function posixJoin(...parts: string[]): string;
+/** `$XDG_CONFIG_HOME`, else `~/.config`. */
+export declare function configHome(ctx: BootProviderContext): string;
+/** `%LOCALAPPDATA%`, else `~\AppData\Local`. */
+export declare function localAppData(ctx: BootProviderContext): string;
+/** A writable scratch directory, used to stage a unit before `sudo install`. */
+export declare function tempDir(ctx: BootProviderContext): string;
+export declare function currentUser(ctx: BootProviderContext): string | null;
+export declare function uidOf(ctx: BootProviderContext): string | null;
+export interface FileOwnership {
+    exists: boolean;
+    owned: boolean;
+    text: string | null;
+    reason: string | null;
+}
+/**
+ * An artifact belongs to this plugin only when it carries the marker. A file
+ * we cannot read is treated as foreign: we must never overwrite or delete a
+ * unit somebody else wrote.
+ */
+export declare function inspectOwned(file: string, marker: string): FileOwnership;
+/** Write our artifact if the bytes differ; never overwrite a foreign one. */
+export declare function writeOwned(file: string, marker: string, content: string, mode?: number): {
+    changed: boolean;
+    refusal: string | null;
+};
+/** Delete our artifact only; a missing file is already the desired state. */
+export declare function removeOwned(file: string, marker: string): {
+    removed: boolean;
+    refusal: string | null;
+};
+export declare function failed(detail: string, extra?: Partial<BootActionResult>): BootActionResult;
+/** Installed + enabled + last run failed is `enabled-failing`; never a guessed success. */
+export declare function bootState(installed: boolean, enabled: boolean, failing: boolean): BootState;
+export declare function isInstalledState(state: BootState): boolean;

package/lib/types/boot/escape.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Escaping for every format this plugin writes.
+ *
+ * None of this builds a shell command: a unit file, a plist, a `.desktop`
+ * entry, a task XML and a registry value each have their own parser, and each
+ * value is quoted for exactly that parser. Values that carry control
+ * characters (newlines included) are rejected outright, because a newline is
+ * how a value escapes its field in every one of these formats.
+ */
+export declare function assertNoControl(value: string, what: string): string;
+export declare function assertUnitName(name: string): string;
+export declare function assertMarker(marker: string): string;
+export declare function assertEnvKey(key: string): string;
+/** POSIX-absolute, Windows-drive-absolute or UNC; checked without consulting the host OS. */
+export declare function isAbsolutePath(value: string): boolean;
+export declare function assertAbsolute(value: string, what: string): string;
+export declare function assertLabel(value: string): string;
+export declare function assertArg(value: string, what?: string): string;
+/** Single-quote a value the way a POSIX shell would, for `commands[]`. */
+export declare function shellQuote(value: string): string;
+/** The exact line a person can paste into a shell. */
+export declare function shellCommand(program: string, args: string[]): string;
+/**
+ * A word in `ExecStart=`/`ExecStop=`. systemd expands `%` specifiers and `$`
+ * variables there before it splits the line, so both are pinned, and `;` — the
+ * multi-command separator — is quoted rather than left bare.
+ */
+export declare function systemdExecWord(value: string): string;
+/**
+ * A single-line free-text setting such as `Description=` (specifiers only).
+ */
+export declare function systemdText(value: string): string;
+/**
+ * A path setting (`WorkingDirectory=`). systemd takes these verbatim — it does
+ * not unquote, and does not unescape `\%` or `\$` — so the only correct
+ * encoding is the raw value; anything that would break the line is refused.
+ */
+export declare function systemdPath(value: string, what?: string): string;
+/** `Environment=KEY=value`, quoted as one assignment when the value needs it. */
+export declare function systemdEnvLine(key: string, value: string): string;
+export declare function xmlEscape(value: string): string;
+export declare function xmlUnescape(value: string): string;
+/** A marker inside an XML comment may not contain `--`. */
+export declare function assertXmlCommentSafe(value: string): string;
+export declare function desktopWord(value: string): string;
+export declare function desktopExec(program: string, args: string[]): string;
+/** A `Key=value` line in a `.desktop` file; the marker is written verbatim. */
+export declare function desktopValue(key: string, value: string): string;
+/** Quote one argv word the way `CreateProcess`/`cmd` parse a command line. */
+export declare function windowsArg(value: string): string;
+export declare function windowsCommandLine(program: string, args: string[]): string;
+/** A line for a `.cmd` wrapper: `%` is a batch metacharacter and is doubled. */
+export declare function batchCommandLine(program: string, args: string[]): string;
+/** A single-quoted PowerShell literal. */
+export declare function powershellLiteral(value: string): string;
+/** Quote one word the way `cmd.exe` takes it, for a copy-pasteable `commands[]` entry. */
+export declare function cmdQuote(value: string): string;
+export declare function windowsDisplayCommand(program: string, args: string[]): string;
+export declare function assertRegistryValueName(name: string): string;

package/lib/types/boot/fallback.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The two terminals of the ladder: a container (an OS boot entry would land
+ * outside it, so the right answer is the container's own restart policy) and a
+ * platform this plugin has no mechanism for.
+ */
+import type { BootProvider, BootProviderContext } from './types.js';
+/** A human-readable description of the container we are inside, or null. */
+export declare function detectContainer(ctx: BootProviderContext): string | null;
+export declare function createContainerProvider(ctx: BootProviderContext): BootProvider;
+export declare function createUnsupportedProvider(platform: NodeJS.Platform): BootProvider;

package/lib/types/boot/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The boot-autostart family: one provider per OS mechanism, ordered into a
+ * ladder. The plugin runs inside dsh, so it can only install, verify and
+ * remove an OS-level entry — it never runs at boot itself.
+ */
+export type { BootActionResult, BootLadder, BootLadderOptions, BootProvider, BootProviderContext, BootProviderStatus, BootRunOptions, BootRunResult, BootRunner, BootSpec, } from './types.js';
+export { bootProviders, createBootLadder } from './ladder.js';
+export { launchdLabel, launchdPlist } from './launchd.js';
+export { systemdSystemUnit, systemdUserUnit } from './systemd.js';
+export { xdgDesktopEntry } from './xdg.js';
+export { registerTaskScript, scheduledTaskXml, unregisterTaskScript, windowsRunPayload } from './windows.js';
+export { detectContainer } from './fallback.js';

package/lib/types/boot/ladder.d.ts

@@ -0,0 +1,4 @@
+import type { BootLadder, BootLadderOptions, BootProvider, BootProviderContext } from './types.js';
+/** Ordered by preference within a platform; the terminal providers come last. */
+export declare function bootProviders(ctx: BootProviderContext, platform?: NodeJS.Platform): BootProvider[];
+export declare function createBootLadder(options?: BootLadderOptions): BootLadder;

package/lib/types/boot/launchd.d.ts

@@ -0,0 +1,8 @@
+import type { BootProvider, BootProviderContext, BootSpec } from './types.js';
+/** Both scopes label with the same reverse-DNS prefix. */
+export declare const LAUNCHD_LABEL_PREFIX = "dev.home-hosted.";
+export declare function launchdLabel(spec: BootSpec): string;
+/** The full property list. The marker rides in an XML comment, which launchd ignores. */
+export declare function launchdPlist(spec: BootSpec): string;
+export declare function createLaunchdAgentProvider(ctx: BootProviderContext): BootProvider;
+export declare function createLaunchdDaemonProvider(ctx: BootProviderContext): BootProvider;

package/lib/types/boot/systemd.d.ts

@@ -0,0 +1,10 @@
+import type { BootProvider, BootProviderContext, BootSpec } from './types.js';
+/** `Type=exec` with an explicit environment; boot capability comes from linger, not from this file. */
+export declare function systemdUserUnit(spec: BootSpec): string;
+/**
+ * The system unit. `StartLimit*` belongs in `[Unit]`, not `[Service]`; `User=`
+ * is written only when we are root and know the target account.
+ */
+export declare function systemdSystemUnit(spec: BootSpec, user?: string | null): string;
+export declare function createSystemdUserProvider(ctx: BootProviderContext): BootProvider;
+export declare function createSystemdSystemProvider(ctx: BootProviderContext): BootProvider;

package/lib/types/boot/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The boot ladder's frozen surface.
+ *
+ * A provider is stateless: everything it needs arrives in `BootSpec` and a
+ * context of injectable seams. Nothing here consults the operating system at
+ * module scope, so importing this family is safe on every platform.
+ */
+import type { BootCandidate, BootMechanism, BootState, BootStatus } from '../shared/contracts.js';
+export interface BootSpec {
+    /** Absolute program (node), never a shim. */
+    command: string;
+    /** Absolute CLI entry plus args. */
+    args: string[];
+    /** Absolute working directory. */
+    cwd: string;
+    /** Absolute values only (PATH, HOME, HHOSTED_HOME, …). */
+    env: Record<string, string>;
+    /** Text identifying this plugin as the writer of an artifact. */
+    marker: string;
+    /** e.g. 'home-hosted'. */
+    unitName: string;
+    /** Human label. */
+    label: string;
+    /** Absolute directory the entry may log into. */
+    logDir: string;
+}
+export interface BootActionResult {
+    ok: boolean;
+    changed: boolean;
+    detail: string;
+    /** Exact commands a person can run when privilege is missing. */
+    commands: string[];
+    needsPrivilege: boolean;
+}
+export interface BootProvider {
+    mechanism: BootMechanism;
+    detect(): Promise<BootCandidate>;
+    status(spec: BootSpec): Promise<{
+        state: BootState;
+        unitPath: string | null;
+        detail: string;
+        commands: string[];
+    }>;
+    install(spec: BootSpec): Promise<BootActionResult>;
+    uninstall(spec: BootSpec): Promise<BootActionResult>;
+}
+/** One injected process result; `run()` from `util/exec.ts` is structurally assignable. */
+export interface BootRunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    error?: string | null;
+}
+export interface BootRunOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+}
+/** argv-only, never a shell. `run` from `util/exec.ts` satisfies this. */
+export type BootRunner = (command: string, args: string[], options?: BootRunOptions) => Promise<BootRunResult>;
+export interface BootProviderContext {
+    platform: NodeJS.Platform;
+    home: string;
+    env: Record<string, string | undefined>;
+    run: BootRunner;
+    sudo: () => Promise<boolean>;
+    isRoot: boolean;
+    /** Existence probe; defaults to `fs.existsSync`. Injected so container/PID-1 detection is testable. */
+    exists?: (file: string) => boolean;
+}
+export interface BootLadderOptions {
+    platform?: NodeJS.Platform;
+    home?: string;
+    env?: Record<string, string | undefined>;
+    run?: BootRunner;
+    sudo?: () => Promise<boolean>;
+    exists?: (file: string) => boolean;
+}
+export interface BootLadder {
+    providers: BootProvider[];
+    detect(): Promise<{
+        platform: BootStatus['platform'];
+        candidates: BootCandidate[];
+    }>;
+    status(spec: BootSpec, mechanism?: BootMechanism): Promise<BootStatus>;
+    install(spec: BootSpec, mechanism?: BootMechanism): Promise<BootActionResult & {
+        mechanism: BootMechanism | null;
+        status: BootStatus;
+    }>;
+    uninstall(spec: BootSpec, mechanism?: BootMechanism): Promise<BootActionResult & {
+        status: BootStatus;
+    }>;
+}
+export type BootProviderStatus = Awaited<ReturnType<BootProvider['status']>>;

package/lib/types/boot/windows.d.ts

@@ -0,0 +1,16 @@
+import type { BootProvider, BootProviderContext, BootSpec } from './types.js';
+export declare const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+export declare const MARKER_KEY = "HKCU\\Software\\home-hosted";
+export interface WindowsRunPayload {
+    /** The exact `Run` value data. */
+    data: string;
+    /** Set when the command line exceeded the `Run` value limit and a `.cmd` wrapper is needed. */
+    wrapperPath: string | null;
+    wrapperContent: string | null;
+}
+export declare function windowsRunPayload(ctx: BootProviderContext, spec: BootSpec): WindowsRunPayload;
+export declare function scheduledTaskXml(spec: BootSpec): string;
+export declare function registerTaskScript(spec: BootSpec): string;
+export declare function unregisterTaskScript(name: string): string;
+export declare function createWindowsTaskProvider(ctx: BootProviderContext): BootProvider;
+export declare function createWindowsRunProvider(ctx: BootProviderContext): BootProvider;

package/lib/types/boot/xdg.d.ts

@@ -0,0 +1,3 @@
+import type { BootProvider, BootProviderContext, BootSpec } from './types.js';
+export declare function xdgDesktopEntry(spec: BootSpec): string;
+export declare function createXdgAutostartProvider(ctx: BootProviderContext): BootProvider;

package/lib/types/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The Cordis row configuration: operator overrides only. Everything a person
+ * changes in the plugin's own page lives in `settings.json` under the plugin
+ * state directory, so the two never fight over the same field.
+ */
+import z from '@deepseek-ai/schemastery';
+export interface Config {
+    /** Override the plugin state directory (defaults to `$DSH_HOME/dsh-home-hosted`). */
+    stateDir?: string;
+    /** Override the home-hosted executable used in generated boot entries. */
+    homeHostedCommand?: string;
+    /** The entry this plugin manages for the running harness. */
+    defaultEntryId: string;
+}
+export declare const Config: z<Config>;

package/lib/types/home-hosted/config-file.d.ts

@@ -0,0 +1,23 @@
+import type { ServerEntry, ServerEntryPatch } from '../shared/contracts.js';
+export interface RawConfig {
+    meta?: Record<string, unknown>;
+    servers?: ServerEntry[];
+    [key: string]: unknown;
+}
+export interface ConfigReadResult {
+    raw: RawConfig | null;
+    exists: boolean;
+    error: string | null;
+}
+export declare function readConfig(home: string): ConfigReadResult;
+/**
+ * Write the file back with home-hosted's own `meta` contract: a config records
+ * the release that wrote it and the shape it wrote, so an unstamped file still
+ * reads as the current schema.
+ */
+export declare function writeConfig(home: string, raw: RawConfig, writtenBy?: string): void;
+export declare function findEntry(raw: RawConfig, id: string): ServerEntry | null;
+/** Insert or replace one entry, preserving every other key in the file. */
+export declare function upsertEntry(raw: RawConfig, entry: ServerEntry): RawConfig;
+export declare function patchEntry(raw: RawConfig, id: string, patch: ServerEntryPatch): RawConfig;
+export declare function removeEntry(raw: RawConfig, id: string): RawConfig;

package/lib/types/home-hosted/dsh-entry.d.ts

@@ -0,0 +1,22 @@
+import type { ServerEntry } from '../shared/contracts.js';
+import type { CliLaunch } from './launch.js';
+/**
+ * Which profile this process is running.
+ *
+ * `DSH_PROFILE` alone is not trustworthy: it can be inherited from a parent
+ * shell that ran a different profile (that is how an entry once ended up booting
+ * `web` under another profile's home). The process's own argv is authoritative,
+ * then the profile directory the launcher pointed at, then the env var.
+ */
+export declare function detectProfile(argv: readonly string[], env?: Record<string, string | undefined>): string;
+export interface DshFacts {
+    id: string;
+    port: number | null;
+    host: string;
+    profile: string | null;
+    dshHome: string;
+    launch: CliLaunch | null;
+}
+/** Where the running harness's own CLI entry is, if we can tell. */
+export declare function resolveDshLaunch(): Promise<CliLaunch | null>;
+export declare function buildDshEntry(facts: DshFacts): ServerEntry;

package/lib/types/home-hosted/entries.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What this plugin decides about a server entry, and how that intent maps onto
+ * the entry: only the keys in `OWNED_ENTRY_KEYS` are ever written, so a person's
+ * own command, args, env, health block and everything else survive untouched.
+ */
+import type { EntryIntent, OnPortConflict, ServerEntry, ServerEntryPatch } from '../shared/contracts.js';
+export declare const DEFAULT_ON_PORT_CONFLICT: OnPortConflict;
+export declare function defaultIntent(id: string): EntryIntent;
+/** The owned keys as a patch, preserving any sibling keys inside `stop`. */
+export declare function ownedPatch(intent: EntryIntent, live?: ServerEntry | null): ServerEntryPatch;
+/** Owned keys whose live value differs from the intent. */
+export declare function ownedDrift(live: ServerEntry | null, intent: EntryIntent): string[];
+/** Only the owned keys, as they were before this plugin touched the entry. */
+export declare function snapshotOwned(live: ServerEntry): ServerEntry;
+/**
+ * Restore an entry to what it was before adoption. A key the snapshot does not
+ * carry was inherited from the panel's defaults, and a PATCH cannot delete a
+ * key, so it is restored to that schema default instead.
+ */
+export declare function restorePatch(live: ServerEntry, snapshot: ServerEntry | null): ServerEntryPatch;

package/lib/types/home-hosted/launch.d.ts

@@ -0,0 +1,25 @@
+import type { BootSpec } from '../boot/types.js';
+export interface CliLaunch {
+    program: string;
+    /** Args that must precede the command, e.g. the CLI entry path. */
+    args: string[];
+    cliEntry: string | null;
+    shimPath: string | null;
+    source: 'override' | 'entry' | 'shim-target' | 'shim';
+}
+export declare function which(command: string): Promise<string | null>;
+/** Turn a resolved CLI path into an absolute program + argv. */
+export declare function resolveShimmedCli(absolute: string, nodePath?: string): CliLaunch | null;
+export declare function resolveHomeHostedLaunch(override?: string | null): Promise<CliLaunch | null>;
+export interface HomeHostedFacts {
+    home: string;
+    projectDir?: string | null;
+    version?: string | null;
+}
+/** A deterministic environment for a boot-time entry, with absolute values. */
+export declare function homeHostedEnv(facts: HomeHostedFacts, launch: CliLaunch, extra?: Record<string, string>): Record<string, string>;
+export interface BootSpecOptions {
+    stateDir: string;
+    marker?: string;
+}
+export declare function buildHomeHostedBootSpec(facts: HomeHostedFacts, launch: CliLaunch, options: BootSpecOptions): BootSpec;

package/lib/types/home-hosted/launcher.d.ts

@@ -0,0 +1,38 @@
+export interface LauncherOptions {
+    stateDir: string;
+    dshHome: string;
+    /** Where the pinned copy is right now; recorded as the fast path. */
+    resolvedEntry: string | null;
+    /** The pinned copy's version, recorded for diagnostics. */
+    resolvedVersion?: string | null;
+    /** The plugin's own package root, as a search hint. */
+    pluginRoot?: string | null;
+    minVersion: string;
+    marker?: string;
+}
+export interface LauncherWrite {
+    path: string;
+    changed: boolean;
+}
+interface LauncherRecord {
+    entry: string | null;
+    version: string | null;
+    pluginRoot: string | null;
+    writtenAt: number;
+}
+export declare function launcherDir(stateDir: string): string;
+export declare function launcherPath(stateDir: string): string;
+export declare function launcherRecordPath(stateDir: string): string;
+export declare function readLauncherRecord(stateDir: string): LauncherRecord | null;
+/** The generated script's source; exported so a test can inspect it. */
+export declare function buildLauncherSource(options: LauncherOptions): string;
+export declare function writeLauncher(options: LauncherOptions): LauncherWrite;
+/** Run the launcher the way the boot entry will, and read the version it answers. */
+export declare function preflightLauncher(stateDir: string, timeoutMs?: number): Promise<string | null>;
+/** The version a CLI entry belongs to, read from the nearest package.json. */
+export declare function versionOfEntry(entry: string): string | null;
+/** Candidate entries under one root: a flat install, or a pnpm store. */
+export declare function candidatesUnder(root: string): string[];
+/** Highest satisfying candidate among explicit roots; exported for tests. */
+export declare function findCandidate(roots: string[], minVersion: string): string | null;
+export {};

package/lib/types/home-hosted/panel-control.d.ts

@@ -0,0 +1,34 @@
+import type { PanelControlResult } from '../shared/contracts.js';
+import { run } from '../util/exec.js';
+import type { CliLaunch } from './launch.js';
+export interface PanelControlDeps {
+    /** The CLI to run, already resolved. */
+    launch: CliLaunch | null;
+    home: string;
+    projectDir?: string | null;
+    stateDir: string;
+    /** Environment for the spawned CLI (absolute PATH, HOME, HHOSTED_HOME). */
+    env: Record<string, string>;
+    timeoutMs?: number;
+}
+/** Start the preferred CLI as a detached panel; the CLI itself does the detaching. */
+export declare function startPanel(deps: PanelControlDeps): Promise<PanelControlResult>;
+export declare function takeoverHelperPath(stateDir: string): string;
+export declare function takeoverLogPath(stateDir: string): string;
+/** The generated helper's source; exported so a test can inspect it. */
+export declare function buildTakeoverSource(deps: PanelControlDeps, oldPid: number | null, marker?: string): string;
+export declare function writeTakeoverHelper(deps: PanelControlDeps, oldPid: number | null): string;
+/**
+ * Spawn the helper detached and return immediately: the old panel's shutdown is
+ * about to stop this very process, so waiting for the result would lose it.
+ */
+export declare function spawnTakeover(deps: PanelControlDeps, oldPid: number | null): PanelControlResult;
+/** Install the pinned range globally, so the `global` preference has something to use. */
+export declare function installGlobal(range: string, options?: {
+    pnpm?: boolean;
+    run?: typeof run;
+}): Promise<{
+    ok: boolean;
+    detail: string;
+    output: string;
+}>;

package/lib/types/home-hosted/panel.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The home-hosted HTTP API client.
+ *
+ * Every call carries the plugin's own API token; the panel verifies it from its
+ * secrets file on each request. A write through this client is the safe path:
+ * the config store records the bytes it wrote, so the panel's own file watcher
+ * never treats the change as an external edit.
+ */
+import type { ServerEntry, ServerEntryPatch, ServerEntryView } from '../shared/contracts.js';
+export declare class PanelError extends Error {
+    readonly code: string;
+    readonly status: number | null;
+    /** The panel's own diagnostic, when it sent one. */
+    readonly detail: unknown;
+    constructor(message: string, code: string, status?: number | null, 
+    /** The panel's own diagnostic, when it sent one. */
+    detail?: unknown);
+}
+export interface PanelClientOptions {
+    baseUrl: string;
+    token: string;
+    timeoutMs?: number;
+}
+export declare class PanelClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly timeoutMs;
+    constructor(options: PanelClientOptions);
+    private request;
+    listServers(): Promise<ServerEntryView[]>;
+    getServer(id: string): Promise<ServerEntryView>;
+    createServer(entry: ServerEntry): Promise<ServerEntryView>;
+    updateServer(id: string, patch: ServerEntryPatch): Promise<ServerEntryView>;
+    deleteServer(id: string): Promise<void>;
+    startServer(id: string): Promise<void>;
+    stopServer(id: string): Promise<void>;
+    restartServer(id: string): Promise<void>;
+    /** Re-list the port's listeners and stop what is not the panel's own tree. */
+    freePort(id: string): Promise<{
+        stopped?: number[];
+    }>;
+}
+/** Prove a token works, without needing any write permission. */
+export declare function verifyToken(baseUrl: string, token: string, timeoutMs?: number): Promise<boolean>;

package/lib/types/home-hosted/resolve.d.ts

@@ -0,0 +1,34 @@
+import type { CliStatus } from '../shared/contracts.js';
+import type { CliLaunch } from './launch.js';
+/** The range the plugin ships and is tested against. */
+export declare const EXPECTED_RANGE = "^0.6.1";
+/** Oldest release whose API and config schema this plugin relies on. */
+export declare const MIN_SUPPORTED_VERSION = "0.4.1";
+/** Oldest release whose config schema accepts `onPortConflict: kill`. */
+export declare const MIN_KILL_VERSION = "0.6.0";
+export type CliPreference = 'pinned' | 'global';
+export interface CliResolution {
+    launch: CliLaunch | null;
+    status: CliStatus;
+}
+export interface ResolveCliOptions {
+    override?: string | null;
+    /** Which copy to run when both exist. */
+    prefer?: CliPreference;
+    /** Test seam: the pinned package's manifest path, or null when it is not installed. */
+    packageManifest?: () => string | null;
+    /** Test seam: ask a CLI for its own version. */
+    readVersion?: (launch: CliLaunch) => Promise<string | null>;
+    /** Test seam: locate a command on PATH. */
+    findOnPath?: (command: string) => Promise<string | null>;
+    timeoutMs?: number;
+}
+/** Where the pinned `home-hosted` manifest is, resolved from this module. */
+export declare function pinnedManifestPath(): string | null;
+/** The `home-hosted` bin entry a package manifest declares. */
+export declare function binEntryFromManifest(manifestPath: string): string | null;
+/** The first `x.y.z[-pre]` in a CLI's output. */
+export declare function parseVersion(output: string | null): string | null;
+/** Numeric comparison; a prerelease sorts below its own release. */
+export declare function compareVersions(a: string, b: string): number;
+export declare function resolveCli(options?: ResolveCliOptions): Promise<CliResolution>;

package/lib/types/home-hosted/runtime.d.ts

@@ -0,0 +1,20 @@
+export interface PanelRuntime {
+    version: string;
+    pid: number;
+    url: string;
+    probeUrl?: string;
+    protocol?: string;
+    port: number;
+    bindHost?: string;
+    projectDir?: string;
+    dataRoot?: string;
+    configPath?: string;
+    logFile?: string;
+}
+export declare function readRuntime(home: string): PanelRuntime | null;
+export declare function pidAlive(pid: number): boolean;
+/**
+ * Ask the panel's public health route whether it is answering. Uses the raw
+ * http/https modules so a self-signed TLS pair answers too.
+ */
+export declare function probePanel(url: string, timeoutMs?: number): Promise<boolean>;

package/lib/types/home-hosted/token.d.ts

@@ -0,0 +1,20 @@
+import type { RunResult } from '../util/exec.js';
+export type CliExecutor = (args: string[], env: Record<string, string | undefined>) => Promise<RunResult>;
+export interface EnsureTokenOptions {
+    home: string;
+    stateDir: string;
+    exec: CliExecutor;
+}
+export interface EnsureTokenResult {
+    token: string | null;
+    /** True when this call created the token. */
+    enrolled: boolean;
+    detail: string;
+}
+export declare function storedTokenPath(stateDir: string): string;
+export declare function readStoredToken(stateDir: string): string | null;
+export declare function storeToken(stateDir: string, token: string): void;
+export declare function generateToken(): string;
+/** Whether home-hosted already holds an API token (only its hash is on disk). */
+export declare function apiTokenEnrolled(home: string): boolean;
+export declare function ensureToken(options: EnsureTokenOptions): Promise<EnsureTokenResult>;

package/lib/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `dsh-home-hosted` — boot autostart for the home-hosted panel, and home-hosted
+ * server management, from inside DeepSeek Harness.
+ *
+ * The plugin supplies no server entries of its own: everything it manages is
+ * declared by the person using the page, and nothing here knows a blessed id
+ * beyond the one it is told to treat as the running harness.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+import type { Config as ConfigShape } from './config.js';
+export declare const name = "dsh-home-hosted";
+export { Config };
+export declare const inject: string[];
+export declare function apply(ctx: Context, config?: ConfigShape): void;

package/lib/types/rpc.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The browser half's one entry point.
+ *
+ * The route is registered on DeepSeek Harness's shared `/api` channel, so the
+ * physical carrier has already applied the Host/Origin fence and browser
+ * authentication before this handler runs: only the local operator reaches it.
+ * Domain failures travel inside the envelope, protocol failures as HTTP status.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { HomeHostedService } from './service.js';
+export declare function registerRpc(ctx: Context, service: HomeHostedService): void;