dsh-plugin-local-infer 0.1.3 → 0.1.4

package/packages/providers/lib/acquire.js

@@ -8,43 +8,82 @@
  * local changes aborts, because a rebase would eat the user's work.
  * @module dsh-plugin-local-infer/providers/acquire
  */
+import { commandLogLine } from '../../core/lib/index.js';
+import { NINFER_LINUX } from "./engines/ninfer/ninferLinux.js";
+import { NINFER_MACOS } from "./engines/ninfer/ninferMacOS.js";
+import { NINFER_WINDOWS } from "./engines/ninfer/ninferWindows.js";
+import { INFERNIX_LINUX } from "./engines/infernix/infernixLinux.js";
+import { INFERNIX_MACOS } from "./engines/infernix/infernixMacOS.js";
+import { INFERNIX_WINDOWS } from "./engines/infernix/infernixWindows.js";
+import { LLAMACPP_LINUX } from "./engines/llamacpp/llamacppLinux.js";
+import { LLAMACPP_MACOS } from "./engines/llamacpp/llamacppMacOS.js";
+import { LLAMACPP_WINDOWS } from "./engines/llamacpp/llamacppWindows.js";
+import { HYPERQWEN_LINUX } from "./engines/hyperqwen/hyperqwenLinux.js";
+import { HYPERQWEN_MACOS } from "./engines/hyperqwen/hyperqwenMacOS.js";
+import { HYPERQWEN_WINDOWS } from "./engines/hyperqwen/hyperqwenWindows.js";
+import { STRATA_LINUX } from "./engines/strata/strataLinux.js";
+import { STRATA_MACOS } from "./engines/strata/strataMacOS.js";
+import { STRATA_WINDOWS } from "./engines/strata/strataWindows.js";
+import { BASALT_LINUX } from "./engines/basalt/basaltLinux.js";
+import { BASALT_MACOS } from "./engines/basalt/basaltMacOS.js";
+import { BASALT_WINDOWS } from "./engines/basalt/basaltWindows.js";
 /**
  * The remote name a user-provided fork is added under, so the checkout's own
  * origin (the upstream it was cloned from) survives the fork override.
  */
 export const FORK_REMOTE = 'dsh-fork';
+/**
+ * The per-engine, per-OS build profiles, keyed by engine id then OS. The
+ * distro-specific Linux profiles (Arch, Debian, Fedora) reuse the shared Linux
+ * profile, so they are not separate keys here. A host OS with no dedicated
+ * profile (a Windows host for an engine that carries no Windows route) reads
+ * the shared Linux profile.
+ */
+const ENGINE_OS_PROFILES = {
+    ninfer: { linux: NINFER_LINUX, macos: NINFER_MACOS, windows: NINFER_WINDOWS },
+    hyperqwen: { linux: HYPERQWEN_LINUX, macos: HYPERQWEN_MACOS, windows: HYPERQWEN_WINDOWS },
+    llamacpp: { linux: LLAMACPP_LINUX, macos: LLAMACPP_MACOS, windows: LLAMACPP_WINDOWS },
+    infernix: { linux: INFERNIX_LINUX, macos: INFERNIX_MACOS, windows: INFERNIX_WINDOWS },
+    strata: { linux: STRATA_LINUX, macos: STRATA_MACOS, windows: STRATA_WINDOWS },
+    basalt: { linux: BASALT_LINUX, macos: BASALT_MACOS, windows: BASALT_WINDOWS },
+};
 /**
  * The per-engine git sources, keyed by engine id. NInfer and Infernix build
  * through cmake (Infernix through its own preset); llama.cpp builds through
  * the same cmake shape as NInfer; Hyper-Qwen is the compose-driven vLLM
  * engine, so it carries no local build steps (the compose up pulls the
  * image); Strata builds through its own setup.sh (the README's
- * Build-from-source route), which the source-build mode runs in the checkout.
+ * Build-from-source route), which the source-build mode runs in the checkout;
+ * Basalt builds through its own CMake route (the Ninja/MSVC variant on
+ * Windows). The build steps are read from the per-engine OS profiles, so a
+ * build command has one home (the OS-specific files under engines/).
  */
 export const ENGINE_SOURCES = {
     ninfer: {
         repo: 'https://github.com/Neroued/ninfer',
         branch: 'master',
-        buildSteps: [
-            'cmake -S {dir} -B {dir}/build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build {dir}/build -j',
-        ],
+        buildSteps: NINFER_LINUX.buildSteps,
+        // The Windows route is the ninfer-all fork's vcpkg build: the manifest
+        // pulls the dev libraries, then the engine's own build-native.bat
+        // configures and builds. The step cds into the checkout first (the {dir}
+        // placeholder), because vcpkg install and the relative script path both
+        // resolve against the checkout root.
+        windowsBuildSteps: NINFER_WINDOWS.buildSteps,
     },
     hyperqwen: {
         repo: 'https://github.com/vllm-project/vllm',
         branch: 'main',
-        buildSteps: [],
+        buildSteps: HYPERQWEN_LINUX.buildSteps,
     },
     llamacpp: {
         repo: 'https://github.com/ggml-org/llama.cpp',
         branch: 'master',
-        buildSteps: [
-            'cmake -S {dir} -B {dir}/build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build {dir}/build -j',
-        ],
+        buildSteps: LLAMACPP_LINUX.buildSteps,
     },
     infernix: {
         repo: 'https://github.com/Wallawalla47/Infernix',
         branch: 'main',
-        buildSteps: ['cd {dir} && cmake --preset release && cmake --build build -j'],
+        buildSteps: INFERNIX_LINUX.buildSteps,
     },
     strata: {
         // The README's Build-from-source route: git clone the repo, then run the
@@ -53,9 +92,50 @@ export const ENGINE_SOURCES = {
         // without starting the server, which the adapter's launch step then does.
         repo: 'https://github.com/Niko1221/Strata',
         branch: 'main',
-        buildSteps: ['cd {dir} && ./setup.sh --yes --no-start'],
+        buildSteps: STRATA_LINUX.buildSteps,
+    },
+    basalt: {
+        // The engine's own CMake route: configure a Release build into the
+        // `build` directory, then compile it. The Windows variant adds the Ninja
+        // generator and runs in the MSVC developer shell (vcvars64.bat).
+        repo: 'https://github.com/jesdga95/basalt',
+        branch: 'main',
+        buildSteps: BASALT_LINUX.buildSteps,
+        windowsBuildSteps: BASALT_WINDOWS.buildSteps,
     },
 };
+/**
+ * engineOsProfile reads the registered build profile for an engine id on an OS,
+ * or undefined when none is registered. A host OS with no dedicated profile
+ * (a Windows host for an engine that carries no Windows route) reads the
+ * shared Linux profile.
+ */
+export function engineOsProfile(engineId, os = 'linux') {
+    const profiles = ENGINE_OS_PROFILES[engineId];
+    if (profiles === undefined)
+        return undefined;
+    return profiles[os] ?? profiles.linux;
+}
+/**
+ * engineBuildDir reads the directory, relative to the checkout, where an
+ * engine's build leaves its binary on an OS, so the binary symlink step reads
+ * the right tree. A Windows host reads the engine's Windows build tree (the
+ * vcpkg route for NInfer writes into build-windows\apps\Release); every other
+ * host reads the shared Linux build directory. An engine that installs its
+ * binary to the path (Strata) carries no build directory, so it reads as
+ * `build`, the shared default.
+ */
+export function engineBuildDir(engineId, os = 'linux') {
+    return engineOsProfile(engineId, os)?.buildDir ?? 'build';
+}
+/**
+ * engineBinary reads the engine binary name on an OS (the .exe on Windows), so
+ * the adapters and the symlink step share one source. An engine with no local
+ * binary (the compose engines) reads as undefined.
+ */
+export function engineBinary(engineId, os = 'linux') {
+    return engineOsProfile(engineId, os)?.binary;
+}
 /**
  * engineSource reads the registered acquisition data for an engine id, or
  * undefined when none is registered.
@@ -64,17 +144,23 @@ export function engineSource(engineId) {
     return ENGINE_SOURCES[engineId];
 }
 /**
- * engineBuildSteps reads the build steps an engine runs in its checkout, so
- * the adapter's deploy step and the Get build step share one list.
+ * engineBuildSteps reads the build steps an engine runs in its checkout for an
+ * OS, so the adapter's deploy step and the Get build step share one list. The
+ * steps come from the engine's OS profile: a Windows host reads the engine's
+ * Windows profile (the vcpkg route for NInfer), and a host OS with no
+ * dedicated profile reads the shared Linux profile.
  */
-export function engineBuildSteps(engineId) {
-    return ENGINE_SOURCES[engineId]?.buildSteps ?? [];
+export function engineBuildSteps(engineId, os = 'linux') {
+    return engineOsProfile(engineId, os)?.buildSteps ?? [];
 }
 /**
  * runLogged runs one shell command through the host's streaming surface when
  * it has one (echoing the command and streaming its output through log), and
  * through plain run otherwise. The streamed copy is also collected, so a
- * caller can price the command's stdout (the dirty-check, for one).
+ * caller can price the command's stdout (the dirty-check, for one). A
+ * `shell` option (the engine OS profile's shell) runs the command in that
+ * shell instead of the host's default. A `needsSudo` option declares the
+ * command runs sudo, so the host applies the sudo-prompt rule to it.
  */
 async function runLogged(host, command, log, options) {
     let output = '';
@@ -83,13 +169,20 @@ async function runLogged(host, command, log, options) {
         log(chunk);
     };
     if (options?.echo !== false) {
-        log(`$ ${command}\n`);
+        log(commandLogLine(command));
     }
+    // exactOptionalPropertyTypes: carry only the options the caller set, so an
+    // absent shell or sudo declaration never passes `{ shell: undefined }`
+    // through.
+    const runOptions = {
+        ...(options?.shell === undefined ? {} : { shell: options.shell }),
+        ...(options?.needsSudo === undefined ? {} : { needsSudo: options.needsSudo }),
+    };
     if (host.runStream !== undefined) {
-        const outcome = await host.runStream(command, collect);
+        const outcome = await host.runStream(command, collect, runOptions);
         return { ...outcome, output };
     }
-    const outcome = await host.run(command);
+    const outcome = await host.run(command, runOptions);
     return { ...outcome, output };
 }
 /**
@@ -98,7 +191,11 @@ async function runLogged(host, command, log, options) {
  * no fork is provided). An existing checkout with local changes aborts, so
  * the user's work is never rebased away; a clean checkout fetches the listed
  * fork (added as the named fork remote when provided, origin when not) and
- * rebases onto its branch. Every command echoes into log as it runs.
+ * rebases onto its branch. Every command echoes into log as it runs. The
+ * result's `cloned` flag names the path taken: set on a fresh clone (the
+ * checkout was absent), absent on the present-checkout path, so a caller
+ * prices a failure's fatality from the flag instead of re-probing the
+ * checkout.
  */
 export async function syncEngineRepo(host, request, log) {
     const source = engineSource(request.engineId);
@@ -110,7 +207,12 @@ export async function syncEngineRepo(host, request, log) {
     }
     const directory = request.directory;
     const fork = request.fork !== undefined && request.fork.trim() !== '' ? request.fork : undefined;
-    const present = await host.run(`[ -d ${directory}/.git ]`);
+    // The presence probe is a git query, not a POSIX [ -d ] test: the shell the
+    // host runs is cmd on Windows, where [ is not a command and the test reads
+    // as a missing checkout every time. rev-parse exits 0 only inside a work
+    // tree, so a real checkout reads as present and an absent or non-git
+    // directory reads as missing, on every platform.
+    const present = await host.run(`git -C ${directory} rev-parse --is-inside-work-tree`);
     if (present.ok) {
         const status = await runLogged(host, `git -C ${directory} status --short`, log);
         if (!status.ok) {
@@ -149,9 +251,9 @@ export async function syncEngineRepo(host, request, log) {
     }
     const clone = await runLogged(host, `git clone ${fork ?? source.repo} ${directory}`, log);
     if (!clone.ok) {
-        return { ok: false, detail: `git clone failed: ${clone.detail ?? 'unknown'}` };
+        return { ok: false, cloned: true, detail: `git clone failed: ${clone.detail ?? 'unknown'}` };
     }
-    return { ok: true };
+    return { ok: true, cloned: true };
 }
 /**
  * syncAndRebuildEngine brings the engine checkout to the listed source and
@@ -185,7 +287,12 @@ export async function syncAndRebuildEngine(host, request, log) {
         chunks.push(chunk);
         log(chunk);
     };
-    const present = await host.run(`[ -d ${directory}/.git ]`);
+    // The presence probe is a git query, not a POSIX [ -d ] test: the shell the
+    // host runs is cmd on Windows, where [ is not a command and the test reads
+    // as a missing checkout every time. rev-parse exits 0 only inside a work
+    // tree, so a real checkout reads as present and an absent or non-git
+    // directory reads as missing, on every platform.
+    const present = await host.run(`git -C ${directory} rev-parse --is-inside-work-tree`);
     let rebuilt = false;
     if (!present.ok) {
         // A missing checkout is a fresh clone of the fork (or the upstream repo),
@@ -205,10 +312,13 @@ export async function syncAndRebuildEngine(host, request, log) {
     else {
         if (fork !== undefined) {
             // Add the fork under its own remote name; a re-launch updates the URL in
-            // place so an edited fork field takes effect on the next run.
-            const add = await runLogged(host, `git -C ${directory} remote add ${FORK_REMOTE} ${fork}`, emit, { echo: false });
+            // place so an edited fork field takes effect on the next run. Both
+            // remote commands mutate the checkout's git config, so their `$ command`
+            // lines lead their output (the TASK-007 exec-audit rule): a re-launch
+            // reads the expected add failure and the set-url that follows.
+            const add = await runLogged(host, `git -C ${directory} remote add ${FORK_REMOTE} ${fork}`, emit);
             if (!add.ok) {
-                await runLogged(host, `git -C ${directory} remote set-url ${FORK_REMOTE} ${fork}`, emit, { echo: false });
+                await runLogged(host, `git -C ${directory} remote set-url ${FORK_REMOTE} ${fork}`, emit);
             }
         }
         const status = await runLogged(host, `git -C ${directory} status --short`, emit, { echo: false });
@@ -225,7 +335,10 @@ export async function syncAndRebuildEngine(host, request, log) {
             return { ok: true, rebuilt: false, logs: chunks.join('') };
         }
         // The fetch is best-effort: an offline host prices the checkout it has.
-        await runLogged(host, `git -C ${directory} fetch ${remote} || true`, emit, { echo: false });
+        // It mutates the checkout's objects and refs, so the `$ command` line
+        // leads its output (the TASK-007 exec-audit rule); the `|| true` keeps a
+        // failed fetch silent so the behind-check prices what is already present.
+        await runLogged(host, `git -C ${directory} fetch ${remote} || true`, emit);
         // Price whether the current branch is behind the remote branch. A fetch
         // that failed (offline) or a missing remote branch reads as not-behind, so
         // the checkout builds as-is.
@@ -277,13 +390,17 @@ export async function syncAndRebuildEngine(host, request, log) {
             : undefined;
         const steps = buildCommands !== undefined
             ? [`cd ${directory} && ${buildCommands}`]
-            : source.buildSteps;
+            : engineBuildSteps(request.engineId, request.os ?? 'linux');
+        // The engine OS profile's shell (the Windows vcpkg route's pwsh.exe)
+        // runs the build steps; absent keeps the host's default shell.
+        const shell = engineOsProfile(request.engineId, request.os ?? 'linux')?.shell;
+        const stepOptions = shell !== undefined ? { shell } : undefined;
         // Report the build phase before the first step runs, so the card's button
         // reads "Building..." while the build is in flight, not after it completes.
         request.onBuildStart?.();
         for (const step of steps) {
             const command = step.replaceAll('{dir}', directory);
-            const outcome = await runLogged(host, command, emit);
+            const outcome = await runLogged(host, command, emit, stepOptions);
             if (!outcome.ok) {
                 return {
                     ok: false,
@@ -295,13 +412,24 @@ export async function syncAndRebuildEngine(host, request, log) {
         }
         // A rebuild that did not install the binary (no make install) leaves it
         // out of the path. Check, and add a symlink when the trust gate allows.
-        const binary = request.binary;
+        // The symlink name is the profile's bare binary (the .exe on Windows), not
+        // the launch path: a Windows launch path carries its build tree
+        // (build-windows\apps\Release\ninfer-serve.exe), so linking it under
+        // buildDir would double the tree.
+        const binary = engineBinary(request.engineId, request.os ?? 'linux');
         if (binary !== undefined) {
             const which = await host.run(`command -v ${binary}`);
             if (!which.ok) {
-                const link = `sudo ln -sf ${directory}/build/${binary} /usr/local/bin/${binary}`;
+                // The build directory is OS-specific: a Windows host reads the
+                // engine's Windows build tree (the vcpkg route for NInfer writes into
+                // build-windows\apps\Release), every other host the shared Linux build
+                // directory.
+                const buildDir = engineBuildDir(request.engineId, request.os ?? 'linux');
+                const link = `sudo ln -sf ${directory}/${buildDir}/${binary} /usr/local/bin/${binary}`;
                 if (request.allowRunDeps === true) {
-                    const result = await runLogged(host, link, emit);
+                    // The hand-written sudo line declares its need at this call site;
+                    // the host never parses the command text to find out.
+                    const result = await runLogged(host, link, emit, { needsSudo: true });
                     if (!result.ok) {
                         emit(`!! ${link} failed: ${result.detail ?? 'unknown'}\n`);
                     }
@@ -314,33 +442,83 @@ export async function syncAndRebuildEngine(host, request, log) {
     }
     return { ok: true, rebuilt, logs: chunks.join('') };
 }
+/**
+ * syncEngineForDeploy runs the deploy step's git sync (the shared
+ * syncAndRebuildEngine) with the option shape every adapter's deploy step
+ * assembles: the platform entry's fork and build-command override, the
+ * Play/Run trust gate, the plan's host OS (the Windows vcpkg route when the
+ * user carries no build-command override), and the progress sink the card's
+ * button reads (the git sync reports "Downloading...", the build step
+ * reports "Building..." the moment it starts). The captured build output is
+ * returned as buildLogs, so a caller threads it to the card's Logs section
+ * without re-running the steps.
+ */
+export async function syncEngineForDeploy(host, request) {
+    // The git sync is the checkout download: the card's button reads
+    // "Downloading..." for it, not "Building...".
+    request.onProgress?.('download');
+    const sync = await syncAndRebuildEngine(host, {
+        engineId: request.engineId,
+        directory: request.directory,
+        ...(request.platform?.engineFork !== undefined
+            ? { fork: request.platform.engineFork }
+            : {}),
+        ...(request.options?.allowRunDeps !== undefined
+            ? { allowRunDeps: request.options.allowRunDeps }
+            : {}),
+        ...(request.platform?.buildCommands !== undefined
+            ? { buildCommands: request.platform.buildCommands }
+            : {}),
+        ...(request.os !== undefined ? { os: request.os } : {}),
+        // Report the build phase the moment the build steps start, so the
+        // card's button reads "Building..." while the build is in flight.
+        onBuildStart: () => request.onProgress?.('build'),
+    }, () => { });
+    // The build output reads as a fresh Logs section: a "Building..."
+    // separator leads the rebuild decision and output, the same line the card
+    // writes when the build step event lands.
+    let buildLogs = sync.logs;
+    if (sync.rebuilt && buildLogs !== '') {
+        buildLogs = `--- Building...\n${buildLogs}`;
+    }
+    return {
+        ok: sync.ok,
+        ...(sync.detail !== undefined ? { detail: sync.detail } : {}),
+        buildLogs,
+    };
+}
 /**
  * buildEngineRepo runs the engine's build steps in the checkout, streaming
  * each step's output through log. An engine with no build steps (the compose
  * engines) passes through with a note; a failing step stops the build with
  * the step's detail.
  */
-export async function buildEngineRepo(host, engineId, directory, log, buildCommands) {
+export async function buildEngineRepo(host, engineId, directory, log, buildCommands, os = 'linux') {
     const source = engineSource(engineId);
     if (source === undefined) {
         return { ok: false, detail: `no engine source is registered for "${engineId}"` };
     }
     // The user's local build command (the card's Build commands field) overrides
     // the engine's default build steps: it runs in the checkout, so it is wrapped
-    // with a cd into the directory. Absent falls back to the engine's steps.
+    // with a cd into the directory. Absent falls back to the engine's steps for
+    // the host OS (the Windows vcpkg route on a Windows host).
     const commands = buildCommands !== undefined && buildCommands.trim() !== '' ? buildCommands : undefined;
-    const steps = commands !== undefined ? [`cd ${directory} && ${commands}`] : source.buildSteps;
+    const steps = commands !== undefined ? [`cd ${directory} && ${commands}`] : engineBuildSteps(engineId, os);
     if (steps.length === 0) {
         log(`no local build steps for ${engineId}\n`);
         return { ok: true };
     }
+    // The engine OS profile's shell (the Windows vcpkg route's pwsh.exe)
+    // runs the build steps; absent keeps the host's default shell.
+    const shell = engineOsProfile(engineId, os)?.shell;
+    const stepOptions = shell !== undefined ? { shell } : undefined;
     for (const step of steps) {
         const command = step.replaceAll('{dir}', directory);
-        const outcome = await runLogged(host, command, log);
+        const outcome = await runLogged(host, command, log, stepOptions);
         if (!outcome.ok) {
             return { ok: false, detail: `build failed: ${outcome.detail ?? 'unknown'}` };
         }
     }
     return { ok: true };
 }
-//# sourceMappingURL=acquire.js.map
+//# sourceMappingURL=acquire.js.map

package/packages/providers/lib/adapters.d.ts

@@ -1,18 +1,31 @@
 /**
  * The shared engine-adapter helpers: the spec-to-argv and spec-to-env
- * translators the concrete adapters (the `engines/*Adapter.ts` files) compose
+ * translators the concrete adapters (the `engines/<engine>/<engine>Adapter.ts`
+ * files) compose
  * into a `LaunchPlan`, the card's Custom Arguments translators, the
  * `LifecycleHost` the deploy, health-check, and stop steps drive, and the
  * health poll. The node implementation (`nodeLifecycleHost`) is what the
  * service wires in on a live host.
  * @module dsh-plugin-local-infer/providers/adapters
  */
-import type { Config, DebugLogger, HealthCheckOptions, HealthResult, LaunchPlan, LifecycleHost, ParameterSpec, ProcessHandle } from '../../core/lib/index.js';
+import type { CommandLogger, CommandOutcome, Config, DebugLogger, HealthCheckOptions, HealthResult, LaunchPlan, LifecycleHost, ParameterDeploy, ParameterSpec, ProcessHandle, RunOptions } from '../../core/lib/index.js';
+/**
+ * deployTargets normalizes a spec's `deploy` declaration into a target list: a
+ * single target wraps in a one-element list, a list passes through, and an
+ * absent `deploy` reads as an empty list (the un-migrated fallback). The
+ * spec-to-spelling helpers key off this list, so a multi-target spec
+ * (cli + env, the Strata shared specs) contributes to every matching helper.
+ */
+export declare function deployTargets(spec: ParameterSpec): readonly ParameterDeploy[];
 /**
  * flagsFromSpecs turns a spec surface and a config into the CLI flag list: each
  * spec's `toArgv` runs over the config value (falling back to the spec
  * default), and empty results are skipped. A spec with no `toArgv` contributes
- * nothing.
+ * nothing. A declared `deploy` target gates the spelling: a `cli` target in the
+ * spec's target list (or no target, the un-migrated fallback that reads the
+ * `toArgv` presence) spells CLI flags, so a spec that deploys only to the env
+ * or a config file contributes no flag even when it carries a `toArgv`
+ * spelling.
  */
 export declare function flagsFromSpecs(specs: readonly ParameterSpec[], config: Config): string[];
 /**
@@ -35,20 +48,72 @@ export declare function customArgFlags(config: Config): string[];
 export declare function customArgEnv(config: Config): Record<string, string>;
 /**
  * envFromSpecs turns a spec surface and a config into the environment map: each
- * spec's `toEnv` runs over the config value (falling back to the spec
- * default). A spec with no `toEnv` contributes nothing.
+ * spec's `toEnv` runs over the config value (falling back to the spec default).
+ * A spec with no `toEnv` contributes nothing. A declared `deploy` target gates
+ * the spelling: an `env` target in the spec's target list (or no target, the
+ * un-migrated fallback that reads the `toEnv` presence) spells env vars, so a
+ * spec that deploys only to the CLI or a config file contributes no var even
+ * when it carries a `toEnv` spelling.
  */
 export declare function envFromSpecs(specs: readonly ParameterSpec[], config: Config): Record<string, string>;
+/**
+ * ConfigFileFormat is the on-disk format a `config` deploy target renders to:
+ * JSON (the built-in stringify), a flat `.env` file, or YAML.
+ */
+export type ConfigFileFormat = 'json' | 'yaml' | 'env';
+/**
+ * configFileFromSpecs turns a spec surface and a config into the content of the
+ * config file the deploy step writes: every spec whose target list carries a
+ * `config` target resolves its value (`toConfig(value) ?? value`, falling back
+ * to the spec default) and nests it under that target's `block` / `key` (the
+ * key defaults to the spec key), then the result renders in the requested
+ * format. A spec with no `deploy`, or no `config` target, contributes nothing.
+ *
+ * A `block` ending in `[]` (e.g. `models[]`) follows the array-entry
+ * convention: the key lands inside the single object of a one-element array
+ * named by the prefix, and every spec sharing that block merges into that one
+ * entry. A plain block name nests as before, into one top-level object.
+ *
+ * A spec that carries both a `config` and a `cli` target contributes nothing
+ * here: the launch spells the CLI flag and leaves the on-disk config file (and
+ * any hand edits in it) untouched. Only a spec whose sole deploy path is the
+ * config file writes it.
+ *
+ * The YAML format loads the `yaml` package lazily (a root devDependency, so the
+ * JSON and env paths never touch it at runtime); a missing package throws only
+ * when the YAML format is requested.
+ */
+export declare function configFileFromSpecs(specs: readonly ParameterSpec[], config: Config, format: ConfigFileFormat): string;
+/**
+ * SudoHook is the optional sudo wiring createNodeLifecycleHost takes: `notify`
+ * announces a guarded command the probe found waiting for a password on the
+ * launching CLI (the service's sudo observer turns it into the Logs note), and
+ * `timeoutMs` overrides the 60 s password deadline. A host built without the
+ * hook never probes, announces, or caps a run.
+ */
+export interface SudoHook {
+    notify: (command: string) => void;
+    timeoutMs?: number;
+}
 /**
  * createNodeLifecycleHost builds the node `LifecycleHost`: `run` through the
  * system shell (a 10-minute cap, so a hung CUDA build cannot hang the panel),
- * `spawn` a detached child the stop step can signal, and `fetch` the health
- * URL. A fetch that throws (no route, connection refused) reads as status 0,
+ * `spawn` a detached child the stop step can signal, `writeFile` the config
+ * file the deploy step renders (creating the parent directory), and `fetch`
+ * the health URL. A fetch that throws (no route, connection refused) reads as status 0,
  * which the poll treats as not-ready. When `debug` is provided, the host logs
  * every command it issues (each `run` line and each `spawn` argv) through it,
- * so a DSH debug-mode host captures the full build-to-launch sequence.
+ * so a DSH debug-mode host captures the full build-to-launch sequence. A
+ * `RunOptions.shell` (the engine OS profile's shell, e.g. pwsh.exe for
+ * the Windows vcpkg route) runs the command line in that shell instead of the
+ * system default. A `RunOptions.graceMs` overrides the 5 s SIGTERM escalation
+ * window of the abort path for that run. The optional `sudo` hook wires the
+ * sudo-prompt rule: a run whose `RunOptions.needsSudo` declares sudo probes
+ * cached credentials first, announces a waiting prompt through the hook once,
+ * and dies at the password deadline with the `sudoFailureDetail` outcome. A
+ * host built without the hook never probes, announces, or caps a run.
  */
-export declare function createNodeLifecycleHost(debug?: DebugLogger): LifecycleHost;
+export declare function createNodeLifecycleHost(debug?: DebugLogger, sudo?: SudoHook): LifecycleHost;
 /**
  * nodeLifecycleHost is the default live host the service wires in: the node
  * implementation with no debug logger, so a normal (non-debug) run logs no
@@ -64,16 +129,75 @@ export declare const nodeLifecycleHost: LifecycleHost;
  * watch (onExit absent) stays tracked until stop removes it.
  */
 export declare function trackChild(children: Map<string, ProcessHandle>, key: string, handle: ProcessHandle): void;
+/**
+ * resolveLaunchArgv resolves a plan's launch argv against the engine
+ * directory the spawn runs in: a relative path that carries a separator (a
+ * build-tree binary, the NInfer Windows tree) is joined into an absolute
+ * path, and a bare name (a binary on the path after the rebuild's symlink
+ * step) is left as-is, so the spawn resolves the right command on every
+ * platform.
+ */
+export declare function resolveLaunchArgv(engineDir: string | undefined, argv: readonly string[] | undefined): string[];
+/**
+ * auditRun runs one mutating host command through the run's log sink: the
+ * `$ <command>` line reaches the sink before the child spawns, and the
+ * outcome's success output tail reaches it after the child settles, so the
+ * launch or stop run reads the command ahead of its result (the URL-query
+ * rule applied to execs: line first, settled outcome after). No sink (a
+ * headless call) and the command runs as before. A failed outcome lands no
+ * output here: the caller's own failure line carries the detail's output
+ * tail. The deploy and stop steps share this one audit rule for their direct
+ * `host.run` calls; the git and build steps run through the acquire step's
+ * own command-first echo.
+ */
+export declare function auditRun(host: LifecycleHost, command: string, log?: CommandLogger, options?: RunOptions): Promise<CommandOutcome>;
+/**
+ * stopProcessPlan signals the engine process a stop targets when the adapter
+ * tracks no child handle for it: an engine a DSH restart re-adopted from a
+ * stored launch record carries no in-memory handle, so the stop signals the
+ * pid the record stamped on the plan (kill on Linux and macOS, taskkill on a
+ * Windows plan). The optional `log` is the stop run's log sink: the signal
+ * command's `$ <command>` line reaches it before the child runs. A plan that
+ * names no pid is a no-op (nothing to signal), and a kill the host reports as
+ * failed throws with the host's detail, so the stop route names the broken
+ * step in the card's Logs section.
+ */
+export declare function stopProcessPlan(host: LifecycleHost, plan: LaunchPlan, log?: CommandLogger): Promise<void>;
+/**
+ * The health poll's defaults: the interval between attempts in ms and the
+ * attempt cap. The service passes the config's healthPollMs and
+ * healthMaxAttempts through, and an adapter that polls without options (or
+ * with a partial one) reads these, so the defaults have one home.
+ */
+export declare const HEALTH_POLL_DEFAULT_MS = 1000;
+export declare const HEALTH_POLL_MAX_ATTEMPTS = 120;
+/**
+ * logHealthPoll brackets a health poll with the URL-query logging rule (the
+ * exec rule's URL twin): the one `> GET <url>` line reaches the run's log
+ * sink before the first request, the retries stay silent, and the settled
+ * verdict line (`> GET <url> ready`, Strata's still-downloading line, or the
+ * `!!` failure with the last detail) lands after the poll returns. The
+ * shared poll and the Strata poll both wrap their loop in this, so the rule
+ * has one home. `log` absent (a headless poll) runs the poll unlogged.
+ */
+export declare function logHealthPoll(log: CommandLogger | undefined, url: string, poll: () => Promise<HealthResult>): Promise<HealthResult>;
 /**
  * pollHealth polls a plan's health URL until a 200 or the attempt cap, the
  * same loop the qwen-ninfer launcher runs. A poll interval of 0 skips the
- * delay, which the tests use to run the loop without a real sleep.
+ * delay, which the tests use to run the loop without a real sleep. `handle`
+ * is the tracked child the deploy step spawned: when it reports it has
+ * exited (hasExited true), the poll ends immediately with a failed result
+ * instead of running the full attempt cap, so a crash reports at once. A
+ * handle that cannot report its exit state (a stub) keeps the full poll.
+ * The poll's URL logging (the one `> GET` line ahead of the settled verdict)
+ * rides the shared logHealthPoll wrap when options.onLog carries the run's
+ * log sink.
  */
-export declare function pollHealth(host: LifecycleHost, plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
+export declare function pollHealth(host: LifecycleHost, plan: LaunchPlan, options?: HealthCheckOptions, handle?: ProcessHandle): Promise<HealthResult>;
 /**
  * delay waits `ms` milliseconds. The health polls use it between attempts; a
  * poll interval of 0 skips the wait, which the tests use to run the loop
  * without a real sleep.
  */
 export declare function delay(ms: number): Promise<void>;
-//# sourceMappingURL=adapters.d.ts.map
+//# sourceMappingURL=adapters.d.ts.map