dsh-home-hosted 0.1.0

package/lib/types/service.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The one implementation behind both surfaces: the browser page and the agent
+ * tools call the same endpoints, so they cannot drift apart.
+ *
+ * Writes prefer the panel API (the store ignores its own writes, so nothing is
+ * restarted behind the user's back) and fall back to an atomic config-file write
+ * only when the panel is not answering.
+ */
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { BootMechanism, BootStatus, HomeHostedStatus, ManagedEntryStatus, PanelControlResult, PanelStatus, RpcEndpoint } from './shared/contracts.js';
+import type { BootSpec } from './boot/types.js';
+import type { SettingsStore } from './settings.js';
+import type { RunResult } from './util/exec.js';
+/** What a boot install/uninstall answers with; mirrors the boot module's shape. */
+export interface BootInstallResult {
+    ok: boolean;
+    changed: boolean;
+    detail: string;
+    commands: string[];
+    needsPrivilege: boolean;
+    /** Present on install; an uninstall names no mechanism. */
+    mechanism?: BootMechanism | null;
+    status: BootStatus;
+}
+/** The subset of the boot ladder this service uses. */
+export interface BootLadderLike {
+    status: (spec: BootSpec, mechanism?: BootMechanism) => Promise<BootStatus>;
+    install: (spec: BootSpec, mechanism?: BootMechanism) => Promise<BootInstallResult>;
+    uninstall: (spec: BootSpec, mechanism?: BootMechanism) => Promise<BootInstallResult>;
+}
+export declare class HomeHostedError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export interface HomeHostedServiceOptions {
+    home: string;
+    stateDir: string;
+    homeHostedCommand?: string;
+    defaultEntryId: string;
+    settings: SettingsStore;
+    /** Test seam: run the home-hosted CLI without spawning it. */
+    execCli?: (args: string[], env: Record<string, string | undefined>) => Promise<RunResult>;
+    /** Test seam: supply the boot ladder instead of probing the real OS. */
+    createLadder?: () => BootLadderLike;
+}
+export declare class HomeHostedService extends Service {
+    private readonly options;
+    private clientCache;
+    private tokenDetail;
+    private readonly snapshotsFile;
+    constructor(ctx: Context, options: HomeHostedServiceOptions);
+    private runtime;
+    /** The entry id this very process was started as, when the panel supervises us. */
+    selfEntryId(): string | null;
+    /** What the config's `meta.writtenBy` names: the panel release when we can read it. */
+    private writtenBy;
+    private webServer;
+    private cliCache;
+    /**
+     * Resolve the preferred CLI, refresh the stable launcher a boot entry runs, and
+     * preflight that launcher the same way the entry will invoke it.
+     */
+    private cli;
+    private panelControlDeps;
+    private cliExec;
+    panelStatus(): Promise<PanelStatus>;
+    private tryClient;
+    private requireClient;
+    private snapshots;
+    private saveSnapshots;
+    private liveEntries;
+    private createEntry;
+    private writeOwned;
+    private panelRunning;
+    /**
+     * The version whose schema will parse what we write: the answering panel, or
+     * the CLI that will parse it next. `kill` did not exist before 0.6.0, and an
+     * older panel refuses to *boot* with it — so this is checked before any write.
+     */
+    private configVersion;
+    private assertPolicySupported;
+    private applyIntents;
+    private restoreEntry;
+    entriesStatus(): Promise<ManagedEntryStatus[]>;
+    private ladder;
+    private bootSpec;
+    bootStatus(mechanism?: BootMechanism): Promise<BootStatus>;
+    installBoot(mechanism?: BootMechanism): Promise<{
+        result: BootInstallResult;
+        status: BootStatus;
+    }>;
+    uninstallBoot(mechanism?: BootMechanism): Promise<{
+        result: BootInstallResult;
+        status: BootStatus;
+    }>;
+    /** Out-of-the-box start: run the preferred CLI's `up`, which detaches itself. */
+    startPanelNow(): Promise<PanelControlResult>;
+    /**
+     * Replace an answering panel with the preferred copy.
+     *
+     * That stops the servers the old panel supervises — this process included — so
+     * the work is handed to a detached helper and the guard demands that this
+     * session is an adopted, autostarting entry the new panel will bring back.
+     */
+    takeoverPanel(force?: boolean): Promise<PanelControlResult>;
+    /** Install the pinned range globally, so the `global` preference has a copy to run. */
+    installGlobalCli(): Promise<PanelControlResult & {
+        output?: string;
+    }>;
+    /** Re-assert an entry that is already installed: a node or CLI upgrade moves the
+     * paths a unit was written with, and the fix is to rewrite it.
+     *
+     * Never installs one that is not there. Installing is a deliberate act — it can
+     * need root and it makes this machine start something at boot — so it happens on
+     * an explicit click or an approved tool call, not as a side effect of startup.
+     */
+    reconcile(): Promise<void>;
+    status(): Promise<HomeHostedStatus>;
+    call(endpoint: RpcEndpoint, payload: unknown): Promise<unknown>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        homeHosted: HomeHostedService;
+    }
+}

package/lib/types/settings.d.ts

@@ -0,0 +1,13 @@
+import type { EntryIntent, PluginSettings, SettingsPatch } from './shared/contracts.js';
+export declare class SettingsStore {
+    readonly file: string;
+    private readonly fallbackEntryId;
+    private current;
+    private readonly listeners;
+    constructor(file: string, fallbackEntryId: string);
+    get(): PluginSettings;
+    /** The intent for an entry, materialising the default when it has none yet. */
+    intentFor(id: string): EntryIntent;
+    update(patch: SettingsPatch): PluginSettings;
+    onChange(listener: (settings: PluginSettings) => void): () => void;
+}

package/lib/types/shared/contracts.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The one wire contract shared by the host half and the browser half.
+ *
+ * Nothing here may import a Node builtin: the browser bundle includes this
+ * module verbatim.
+ */
+/** Exact Fetch route registered on DeepSeek Harness's authenticated `/api` channel. */
+export declare const RPC_PATH = "/home-hosted";
+/** Bumped when a payload shape changes; a mismatch is reported, never guessed at. */
+export declare const RPC_VERSION = 1;
+export interface RpcError {
+    code: string;
+    message: string;
+    detail?: unknown;
+}
+export type Envelope<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: RpcError;
+};
+/** Endpoints the browser and the agent tools both speak. */
+export type RpcEndpoint = 'status' | 'servers.list' | 'servers.get' | 'servers.create' | 'servers.update' | 'servers.delete' | 'servers.start' | 'servers.stop' | 'servers.restart' | 'servers.freePort' | 'entries.apply' | 'entries.restore' | 'boot.install' | 'boot.uninstall' | 'boot.verify' | 'panel.start' | 'panel.takeover' | 'cli.installGlobal' | 'settings.update';
+/** A settings write sends only the changed subtree; the host merges group by group. */
+export interface SettingsPatch {
+    autostart?: Partial<PluginSettings['autostart']>;
+    entries?: PluginSettings['entries'];
+    agentTools?: Partial<PluginSettings['agentTools']>;
+    cli?: Partial<PluginSettings['cli']>;
+}
+export interface EndpointPayloads {
+    'status': {
+        refresh?: boolean;
+    };
+    'servers.list': Record<string, never>;
+    'servers.get': {
+        id: string;
+    };
+    'servers.create': {
+        entry: ServerEntry;
+    };
+    'servers.update': {
+        id: string;
+        patch: ServerEntryPatch;
+    };
+    'servers.delete': {
+        id: string;
+    };
+    'servers.start': {
+        id: string;
+    };
+    'servers.stop': {
+        id: string;
+    };
+    'servers.restart': {
+        id: string;
+    };
+    'servers.freePort': {
+        id: string;
+    };
+    'entries.apply': {
+        intents: EntryIntent[];
+    };
+    'entries.restore': {
+        id: string;
+    };
+    'boot.install': {
+        mechanism?: BootMechanism;
+    };
+    'boot.uninstall': {
+        mechanism?: BootMechanism;
+    };
+    'boot.verify': Record<string, never>;
+    /** Start the preferred CLI as a detached panel; refused while one already answers. */
+    'panel.start': Record<string, never>;
+    /** Stop the answering panel and start the preferred copy instead. */
+    'panel.takeover': {
+        force?: boolean;
+    };
+    /** Install the pinned range as a global CLI, so the `global` preference can use it. */
+    'cli.installGlobal': Record<string, never>;
+    'settings.update': {
+        patch: SettingsPatch;
+    };
+}
+export interface RpcRequest {
+    v: number;
+    endpoint: RpcEndpoint;
+    payload?: unknown;
+}
+export type OnPortConflict = 'block' | 'warn' | 'follow' | 'reclaim' | 'kill';
+/** Only the fields this plugin reads or writes are typed; the rest is preserved. */
+export interface ServerEntry {
+    id: string;
+    label?: string;
+    enabled?: boolean;
+    autostart?: boolean;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    dataEnvs?: Record<string, string>;
+    port?: number | null;
+    bind?: string;
+    onPortConflict?: OnPortConflict;
+    stop?: {
+        killPortHolders?: boolean;
+        [key: string]: unknown;
+    };
+    health?: Record<string, unknown>;
+    restart?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export type ServerEntryPatch = Partial<ServerEntry>;
+/** What the plugin decides about one entry, and the keys it therefore owns. */
+export interface EntryIntent {
+    id: string;
+    autostart: boolean;
+    onPortConflict: OnPortConflict;
+    stopKillPortHolders: boolean;
+}
+/** Keys an intent owns: a patch touches these and nothing else. */
+export declare const OWNED_ENTRY_KEYS: readonly ["autostart", "onPortConflict", "stop"];
+export interface ServerEntryView {
+    id: string;
+    status: string;
+    pid: number | null;
+    url: string | null;
+    config: ServerEntry;
+}
+export interface ManagedEntryStatus {
+    intent: EntryIntent;
+    exists: boolean;
+    /** True once the plugin has adopted the entry and holds a snapshot of what it was. */
+    managed: boolean;
+    /** Owned keys whose live value differs from the intent. */
+    drift: string[];
+    live: ServerEntryView | null;
+    snapshot: ServerEntry | null;
+}
+export type TokenState = 'enrolled' | 'present' | 'absent' | 'unknown';
+export interface PanelStatus {
+    /** `$HHOSTED_HOME` this plugin resolved, whether or not the panel answers. */
+    home: string;
+    reachable: boolean;
+    url: string | null;
+    version: string | null;
+    pid: number | null;
+    /** How writes are authenticated right now. */
+    writeVia: 'api' | 'file' | 'none';
+    token: TokenState;
+    detail: string;
+}
+/** Which home-hosted CLI the plugin drives, and where it came from. */
+export type CliSource = 'config' | 'dependency' | 'path' | 'none';
+/** One place a CLI could come from, with the version found there. */
+export interface CliCandidate {
+    source: 'config' | 'dependency' | 'path';
+    path: string | null;
+    version: string | null;
+}
+export interface PanelControlResult {
+    ok: boolean;
+    detail: string;
+    url?: string | null;
+    version?: string | null;
+}
+export interface CliStatus {
+    /** `config` (operator override), `dependency` (the pinned copy), `path`, or none. */
+    source: CliSource;
+    path: string | null;
+    version: string | null;
+    /** The range the plugin ships in its own dependencies. */
+    expectedRange: string;
+    /** False when the resolved CLI is older than the oldest release this plugin supports. */
+    supported: boolean;
+    /** The stable launcher a boot entry runs instead of a moving node_modules path. */
+    launcherPath?: string | null;
+    /** What the launcher answers right now, as the boot entry would invoke it. */
+    launcherVersion?: string | null;
+    /** Which copy the plugin prefers. */
+    prefer?: 'pinned' | 'global';
+    /** The plugin's own copy, when it resolves. */
+    dependency?: CliCandidate | null;
+    /** The global install on PATH, when there is one. */
+    global?: CliCandidate | null;
+    detail: string;
+}
+export type BootMechanism = 'systemd-user' | 'systemd-system' | 'xdg-autostart' | 'launchd-agent' | 'launchd-daemon' | 'windows-run' | 'windows-task' | 'container' | 'unsupported';
+export type BootState = 'not-installed' | 'installed-disabled' | 'enabled-running' | 'enabled-failing' | 'unsupported';
+export interface BootCandidate {
+    mechanism: BootMechanism;
+    available: boolean;
+    /** Starts before an interactive login. */
+    bootCapable: boolean;
+    /** This process can drive it without an elevation prompt. */
+    privileged: boolean;
+    reason: string;
+}
+export interface BootStatus {
+    platform: 'linux' | 'darwin' | 'win32' | 'other';
+    mechanism: BootMechanism | null;
+    recommended: BootMechanism | null;
+    state: BootState;
+    bootCapable: boolean;
+    privileged: boolean;
+    unitPath: string | null;
+    /** Exact commands a person can run when this process cannot elevate. */
+    commands: string[];
+    detail: string;
+    candidates: BootCandidate[];
+}
+export type AgentToolName = 'status' | 'servers_list' | 'servers_start' | 'servers_stop' | 'servers_restart' | 'servers_create' | 'servers_update' | 'servers_delete' | 'autostart_install' | 'autostart_uninstall';
+export declare const AGENT_TOOL_NAMES: readonly AgentToolName[];
+/** Tools that change something; every one of them asks for approval first. */
+export declare const MUTATING_AGENT_TOOLS: readonly AgentToolName[];
+export interface PluginSettings {
+    autostart: {
+        enabled: boolean;
+        /** `auto` picks the best available mechanism; an explicit one is honoured only when available. */
+        mechanism: 'auto' | BootMechanism;
+    };
+    entries: EntryIntent[];
+    agentTools: {
+        enabled: boolean;
+        allow: AgentToolName[];
+    };
+    cli: {
+        /** `pinned` runs the copy this plugin ships; `global` runs the one on PATH. */
+        prefer: 'pinned' | 'global';
+    };
+}
+export declare const DEFAULT_SETTINGS: PluginSettings;
+export interface HomeHostedStatus {
+    panel: PanelStatus;
+    boot: BootStatus;
+    entries: ManagedEntryStatus[];
+    servers: ServerEntryView[];
+    settings: PluginSettings;
+    /** The CLI the plugin drives; absent only from a host older than this field. */
+    cli?: CliStatus;
+    /** Set when the panel could not be reached, so the UI can show a degraded page. */
+    lastError: string | null;
+}

package/lib/types/tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent tools, off by default and allowlisted by name.
+ *
+ * The list is read at registration time and re-read whenever the settings file
+ * changes, so toggling a tool takes effect without a restart. Every tool that
+ * changes something asks the approval service first and fails closed when it is
+ * absent or refuses.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentToolName } from './shared/contracts.js';
+import type { HomeHostedService } from './service.js';
+import type { SettingsStore } from './settings.js';
+export declare function toolNameFor(name: AgentToolName): string;
+export declare function registerAgentTools(ctx: Context, service: HomeHostedService, settings: SettingsStore): void;

package/lib/types/util/exec.d.ts

@@ -0,0 +1,29 @@
+export interface RunOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+    /** Cap on each captured stream; a chatty command is truncated, not buffered forever. */
+    maxBytes?: number;
+}
+export interface RunResult {
+    command: string;
+    args: string[];
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    error: string | null;
+}
+/** Run a program and always resolve; a non-zero code is data, not a throw. */
+export declare function run(command: string, args?: string[], options?: RunOptions): Promise<RunResult>;
+/** Run a program and fail loudly on anything but success. */
+export declare function runOk(command: string, args?: string[], options?: RunOptions): Promise<RunResult>;
+/** True when the program exists and answers to `--version` or similar. */
+export declare function hasCommand(command: string): Promise<boolean>;
+/**
+ * Whether this process can run one privileged command with no prompt.
+ * `sudo -n` never asks for a password, so a failure is a definitive "not
+ * available" rather than something to retry interactively.
+ */
+export declare function sudoAvailable(): Promise<boolean>;

package/lib/types/util/fsx.d.ts

@@ -0,0 +1,9 @@
+export declare function fileExists(file: string): boolean;
+export declare function readText(file: string): string | null;
+export declare function readJson<T>(file: string): T | null;
+export declare function ensureDir(dir: string, mode?: number): void;
+/** Write a file through a sibling temp file, then rename it into place. */
+export declare function writeFileAtomic(file: string, data: string, mode?: number): void;
+export declare function writeJsonAtomic(file: string, value: unknown, mode?: number): void;
+/** Best-effort removal; a missing file is not an error. */
+export declare function removeFile(file: string): void;

package/lib/types/util/paths.d.ts

@@ -0,0 +1,12 @@
+export declare function expandHome(value: string): string;
+/** DeepSeek Harness home: `$DSH_HOME`, else `~/.dsh`. */
+export declare function dshHome(): string;
+/** home-hosted state root: `$HHOSTED_HOME`, else `~/.home-hosted`. */
+export declare function homeHostedHome(): string;
+/** Where this plugin keeps its own durable state (settings, snapshots, token). */
+export declare function pluginStateDir(override?: string): string;
+/** home-hosted's own tokens file, written by the panel at startup. */
+export declare function runtimeFile(home?: string): string;
+/** home-hosted's secrets file (0600): proves whether an API token is enrolled. */
+export declare function secretsFile(home?: string): string;
+export declare function configFile(home?: string): string;

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "dsh-home-hosted",
+  "version": "0.1.0",
+  "description": "Boot autostart for home-hosted and home-hosted server management from DeepSeek Harness.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NamesMT/dsh-home-hosted.git"
+  },
+  "homepage": "https://github.com/NamesMT/dsh-home-hosted#readme",
+  "bugs": {
+    "url": "https://github.com/NamesMT/dsh-home-hosted/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "home-hosted",
+    "autostart",
+    "systemd",
+    "launchd"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "docs/DESIGN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs && node scripts/build-client.mjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:host": "node scripts/build.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "prepack": "pnpm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-connection": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "esbuild": "^0.24.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "home-hosted": "^0.6.1"
+  }
+}