@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/cli/service/backup-timer.d.ts

@@ -1,14 +1,9 @@
 /**
- * Scheduled orchestrator database backups.
- *
- * Renders and registers a `kici-<instance>-db-backup` service + timer pair that
- * runs `kici-admin db backup --output-dir <dir> --keep <n>` on a calendar
- * schedule. systemd gets a `.service` plus a `.timer`; launchd gets one plist
- * with a `StartCalendarInterval`.
- *
- * Windows and Compose are refused: `sc.exe` has no timer concept, and a
- * Compose orchestrator runs in a container whose host scheduler KiCI does not
- * own. Both refusals name the platform-native equivalent.
+ * Scheduled database backups: a `kici-<instance>-db-backup` unit that runs
+ * `kici-admin db backup --output-dir <dir> --keep <n>` on a calendar (systemd
+ * `.service` + `.timer`; one launchd plist with `StartCalendarInterval`).
+ * Windows (`sc.exe` has no timers) and Compose (KiCI does not own the host
+ * scheduler) are refused with the platform-native equivalent.
  */
 import type { ServicePlatform } from './types.js';
 /** Default retention: keep the last week of daily dumps. */
@@ -20,33 +15,21 @@ export interface BackupTimerConfig {
     serviceName: string;
     /** Calendar spec: a systemd `OnCalendar=` value, or `daily` / `HH:MM`. */
     schedule: string;
-    /** Directory the timestamped dumps are written to. */
     outputDir: string;
-    /** How many dumps to retain after each run. */
     keep: number;
-    /** Node binary the scheduled unit runs. */
     nodeBinPath: string;
-    /** `kici-admin` entry script the scheduled unit runs. */
     cliScriptPath: string;
     /** Env file carrying `KICI_DATABASE_URL` for the scheduled run. */
     envFilePath: string;
     /** User-level (`systemctl --user`, LaunchAgent) vs system-level. */
     isUserLevel: boolean;
-    /** Account a system-level unit runs as. */
     user?: string;
 }
-/**
- * `kici-orchestrator` -> `kici-orchestrator-db-backup`. A name that already
- * carries the `kici-` prefix keeps exactly one, so the unit is always
- * `kici-<instance>-db-backup`.
- */
+/** `kici-orchestrator` -> `kici-orchestrator-db-backup`: always exactly one `kici-` prefix. */
 export declare function backupTimerName(serviceName: string): string;
 /** The argv the scheduled unit executes, after the node binary. */
 export declare function backupCommandArgs(config: BackupTimerConfig): string[];
-/**
- * Explain why a platform cannot carry a KiCI-managed backup timer, and what to
- * use instead. Returns null when the platform is supported.
- */
+/** Why a platform cannot carry a KiCI backup timer and what to use instead; null when supported. */
 export declare function unsupportedPlatformMessage(platform: ServicePlatform, outputDir: string, keep: number): string | null;
 /** Throw the {@link unsupportedPlatformMessage} refusal, if there is one. */
 export declare function assertTimerPlatformSupported(platform: ServicePlatform, outputDir: string, keep: number): void;
@@ -55,29 +38,23 @@ export declare function renderSystemdBackupService(config: BackupTimerConfig): s
 /** Render the systemd `.timer` unit that schedules the backup service. */
 export declare function renderSystemdBackupTimer(config: BackupTimerConfig): string;
 /**
- * Translate a calendar spec into the launchd `StartCalendarInterval` fields.
- * launchd has no calendar-expression parser, so only the two forms that map
- * cleanly are accepted; anything else is refused by name.
+ * Calendar spec to launchd `StartCalendarInterval` fields. launchd has no
+ * calendar-expression parser, so only `daily` and `HH:MM` are accepted.
  */
 export declare function parseLaunchdSchedule(schedule: string): {
     hour: number;
     minute: number;
 };
 /**
- * Read one key out of a `KEY=value` env file. Returns undefined when the file
- * or the key is absent — the caller decides whether that is fatal.
+ * Read one key out of a `KEY=value` env file; undefined when absent.
  *
- * The value is trimmed and stripped of surrounding quotes, because these files
- * are hand-edited as often as they are generated: a path written as
- * `"/etc/kici/scalers.yaml"` or left with a trailing space names the same file
- * and must read back the same way. Only the outer quote characters go — an
- * embedded `=` stays, so `B=two=three` still reads as `two=three`.
+ * The value is trimmed and its outer quotes stripped, since these files are
+ * hand-edited: `"/etc/kici/scalers.yaml"` names the same file. An embedded `=`
+ * stays (`B=two=three` reads `two=three`).
  *
- * A duplicated key takes its **last** occurrence, because that is the value the
- * running process holds: systemd's `EnvironmentFile=` applies each assignment in
- * order, so the last one wins. Reporting an earlier one would name a path or a
- * database the service never used, which is the opposite of what these readers
- * are for. Every other env-file reader in the repo takes the last occurrence too.
+ * A duplicated key takes its **last** occurrence, the value the running process
+ * holds (systemd's `EnvironmentFile=` applies assignments in order), like every
+ * other env-file reader in the repo.
  */
 export declare function readEnvValue(content: string, key: string): string | undefined;
 /** Render the launchd plist that schedules the backup run. */

package/dist/cli/service/compose-path.d.ts

@@ -1,11 +1,7 @@
 /**
- * Where the generated compose file for a service lives: beside its env file,
- * named for the service.
- *
- * This sits in its own module because two callers need it and they cannot
- * share `compose.ts` — that module also detects a container runtime, which the
- * env-file writer has no business pulling in. One definition means the naming
- * convention is written down once rather than re-derived at each site.
+ * The generated compose file sits beside the env file, named for the service.
+ * Its own module so the env-file writer need not import `compose.ts`, which
+ * also detects a container runtime.
  */
 export declare function composeFilePath(envFilePath: string, serviceName: string): string;
 //# sourceMappingURL=compose-path.d.ts.map

package/dist/cli/service/compose.d.ts

@@ -1,20 +1,13 @@
 /**
- * Docker/Podman Compose service manager.
- *
- * Generates compose YAML files and manages service lifecycle via
- * `docker compose` or `podman compose` (auto-detected). Provides
- * a container-based service management backend that works on any
- * platform with Docker or Podman installed.
+ * Compose service manager: writes compose YAML and drives the lifecycle via
+ * `podman compose` or `docker compose` (auto-detected), on any platform.
  */
 import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
 /** Container runtime binary (`podman` or `docker`); compose form is `${runtime} compose`. */
 type Runtime = 'podman' | 'docker';
 /**
- * Detect which container runtime is available.
- * Tries podman compose first, then docker compose.
- *
- * Exported so the orchestrator installer can resolve the runtime once when
- * injecting the `KICI_DEPLOY_CONTAINER_RUNTIME` env var for a compose deploy.
+ * Tries podman compose, then docker compose. Exported for the installer, which
+ * resolves it once to inject `KICI_DEPLOY_CONTAINER_RUNTIME` for a compose deploy.
  *
  * @throws When neither runtime is found.
  */
@@ -23,29 +16,18 @@ export declare class ComposeServiceManager implements ServiceManager {
     readonly platform: 'compose';
     private runtime;
     /**
-     * True when the container runtime's own registry answers. A host with
-     * neither podman nor docker cannot hold a running compose install, and a
-     * host whose runtime is momentarily down still holds its installs — so
-     * discovery reads a `false` here as "do not touch this platform's index
-     * rows" rather than as an empty scan.
-     *
-     * Both halves are needed, and the second is the one that costs something.
-     * `<runtime> compose version` is answered by the compose client alone: with
-     * dockerd stopped it still exits 0 (measured), so a client-only probe reports
-     * available, `list()` then gets an error it cannot distinguish from an empty
-     * registry, and the reconcile prunes live rows. The `RUNTIME_PROBE_TIMEOUT_MS`
-     * bound does not cover this — the client answers instantly whether or not the
-     * daemon is there, so there is nothing for a timeout to catch.
+     * True when the runtime's registry answers. A host whose runtime is briefly
+     * down still holds its installs, so discovery reads `false` as "leave this
+     * platform's index rows alone", not as an empty scan.
      *
-     * `ps -q` is the cheapest question only the registry can answer (0.02s
-     * docker / 0.07s podman on a healthy host), and it fails the same two ways
-     * the scan itself would: non-zero for a daemon that is down, and a timeout
-     * kill for one that is hung.
+     * `compose version` alone is not enough: the client answers it with dockerd
+     * stopped (measured), so `list()` would then fail like an empty registry and
+     * the reconcile would prune live rows; no timeout catches an instant answer.
+     * `ps -q` is the cheapest registry-only question (0.02s docker / 0.07s
+     * podman), failing as the scan would: non-zero when down, timeout when hung.
      */
     available(): Promise<boolean>;
-    /** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
     private getRuntime;
-    /** Run a compose command for the given service config. */
     private runCompose;
     install(config: ServiceConfig): Promise<void>;
     uninstall(config: ServiceConfig): Promise<void>;

package/dist/cli/service/deploy-env.d.ts

@@ -1,30 +1,18 @@
 import type { ServicePlatform } from './types.js';
-/** Inputs the installer already has when it writes the env file. */
 export interface DeployEnvInput {
     platform: ServicePlatform;
-    /** The service / container name the installer assigns (= ServiceConfig.name). */
+    /** = ServiceConfig.name. */
     serviceName: string;
-    /** Container runtime, only meaningful for the `compose` platform. */
+    /** `compose` platform only. */
     containerRuntime?: 'podman' | 'docker';
     /**
-     * Absolute path of the env file the installer is writing. Stamped into the
-     * file itself because the running process cannot derive it: systemd's
-     * `EnvironmentFile=` delivers the variables and not the filename, and a
-     * compose container never sees the host path at all.
+     * Stamped into the file because the process cannot derive it: systemd's
+     * `EnvironmentFile=` passes no filename, and a container never sees the host path.
      */
     envFilePath: string;
 }
-/**
- * Build the `KICI_DEPLOY_*` env lines for a given deployment shape. The mode
- * and config-file lines are always emitted; the container name, runtime, and
- * compose file are emitted only for the `compose` platform (the only shape
- * with a container to `exec` into and a generated compose file to read).
- */
+/** Container lines only for `compose`, the one shape with a container and a compose file. */
 export declare function buildDeployEnvLines(input: DeployEnvInput): string[];
-/**
- * Append the freshly-computed deploy lines to existing env-file content,
- * idempotently: any pre-existing `KICI_DEPLOY_*` line is stripped first so a
- * re-install / upgrade heals the shape rather than duplicating it.
- */
+/** Idempotent: existing `KICI_DEPLOY_*` lines are stripped so a re-install heals the shape. */
 export declare function upsertDeployEnvLines(existingContent: string, lines: string[]): string;
 //# sourceMappingURL=deploy-env.d.ts.map

package/dist/cli/service/entrypoint.d.ts

@@ -1,32 +1,24 @@
 /**
- * Resolves the command a service unit should run.
- *
- * A `npm install -g kici-admin` install exposes only the `kici-admin` /
- * `kici-agent` CLI bins — the long-running orchestrator and agent servers are
- * separate module entry points (`dist/server.js` / `dist/standalone.js`) that
- * must be launched with `node <script>`. These helpers turn an install's
- * options into the `{ executablePath, args }` pair the platform service
- * managers write into the unit's run command.
+ * Resolves the command a service unit runs. `npm install -g kici-admin` exposes
+ * only the `kici-admin` / `kici-agent` CLI bins; the orchestrator and agent
+ * servers are module entry points (`dist/server.js` / `dist/standalone.js`)
+ * launched with `node <script>`.
  */
-/** Server entry point variant for the orchestrator. */
 export type ServerEntry = 'server' | 'standalone';
-/** Resolved run command for a service unit. */
 export interface ServiceExecutable {
-    /** Program the unit runs (the Node binary, or an explicit self-launching binary). */
+    /** The Node binary, or an explicit self-launching binary. */
     executablePath: string;
-    /** Arguments passed to the program (the resolved server script, or none). */
+    /** The resolved server script, or none. */
     args: string[];
 }
 /**
- * Pick the orchestrator server entry from an env file's `KICI_MODE`.
- * `independent` runs the standalone server; `platform` / `hybrid` / unset run
- * the Platform-connected server.
+ * From `KICI_MODE`: `independent` runs the standalone server; `platform` /
+ * `hybrid` / unset run the Platform-connected server.
  */
 export declare function selectServerEntry(envFileContent: string): ServerEntry;
 /**
- * Build the `{ executablePath, args }` for a service unit.
- * - An explicit `binary` is run directly (assumed self-launching), no args.
- * - Otherwise the Node binary runs the resolved server `entryScript`.
+ * An explicit `binary` runs directly (assumed self-launching), no args;
+ * otherwise the Node binary runs the resolved server `entryScript`.
  */
 export declare function resolveServiceExecutable(opts: {
     binary?: string;
@@ -34,12 +26,10 @@ export declare function resolveServiceExecutable(opts: {
     entryScript?: string;
 }): ServiceExecutable;
 /**
- * The path of a server entry script installed beside this CLI, for a service
- * that runs `node <script>`. `resolve` is the calling module's
- * `import.meta.resolve`, or undefined where the CLI has none: a kici-admin from a
- * standalone package is a single CommonJS bundle that carries no orchestrator
- * or agent server. Either way the error names `--binary`, the launcher the
- * service runs instead.
+ * The path of a server entry script installed beside this CLI. `resolve` is the
+ * caller's `import.meta.resolve`, undefined in a standalone-package kici-admin
+ * (a single CommonJS bundle with no orchestrator or agent server). The error
+ * names `--binary`, the launcher the service runs instead.
  */
 export declare function resolveServerScript(specifier: string, component: ServerComponent, resolve: ModuleResolver | undefined): string;
 /**
@@ -48,7 +38,6 @@ export declare function resolveServerScript(specifier: string, component: Server
  */
 export declare function assertServerResolvable(component: ServerComponent, binary: string | undefined, resolve: ModuleResolver | undefined): void;
 type ServerComponent = 'orchestrator' | 'agent';
-/** A module's `import.meta.resolve`. */
 export type ModuleResolver = (specifier: string) => string;
 export {};
 //# sourceMappingURL=entrypoint.d.ts.map

package/dist/cli/service/env-assignment.d.ts

@@ -1,24 +1,13 @@
 /**
- * Single-variable upsert for service env-file content.
- *
- * The sibling {@link ./deploy-env.js} upserts a whole `KICI_DEPLOY_*` block by
- * stripping the prefix and re-appending it. A variable an operator may also
- * have set by hand needs the narrower shape: replace the assignment where it
- * already sits, so the comment above it still describes the value below it.
- */
-/**
- * Whether `content` carries an uncommented assignment of `name`.
- *
- * A `#`-prefixed mention does not count: it is documentation, and the readers
- * that matter (systemd's `EnvironmentFile=`, `selectServerEntry`) skip it.
+ * Single-variable env-file upsert. Unlike {@link ./deploy-env.js}, which
+ * re-appends a whole `KICI_DEPLOY_*` block, it replaces a hand-settable
+ * variable in place, so the comment above still describes the value below.
  */
+/** A `#` mention does not count: systemd's `EnvironmentFile=` and `selectServerEntry` skip it. */
 export declare function hasEnvAssignment(content: string, name: string): boolean;
 /**
- * Return `content` with `name` assigned `value`.
- *
- * Every uncommented assignment of `name` is rewritten in place; a file that
- * declares it nowhere gains the assignment on its last line. Commented lines
- * are left alone, so a stub's explanatory `# KICI_MODE=...` survives.
+ * Rewrites every uncommented assignment of `name` in place, or appends one.
+ * Commented lines survive, such as a stub's `# KICI_MODE=...`.
  */
 export declare function upsertEnvAssignment(content: string, name: string, value: string): string;
 //# sourceMappingURL=env-assignment.d.ts.map

package/dist/cli/service/image-digests.d.ts

@@ -1,15 +1,9 @@
 /**
- * Resolves the customer installer's image reference from the digest record
- * shipped with this package (installer-image-digests.json at the package root).
- *
- * Emits a manifest-list-digest-pinned ref so a `docker`/`podman pull` verifies
- * the image hash — a registry that serves substituted bits fails the pull. When
- * the record is missing (a dev tree that never ran a release) or lacks the
- * image, falls back to the moving `:latest` tag and warns.
- *
- * The record resolves relative to this module's directory and works for both
- * layouts: the source tree (`src/cli/service/` → the JSON is three dirs up at
- * the package root) and the single-file bundle (`dist/cli.js` → one dir up).
+ * The installer's image reference, from the digest record at the package root.
+ * The ref is pinned to the manifest-list digest, so a `docker`/`podman pull`
+ * of substituted bits fails. Without a record (a dev tree that never ran a
+ * release) or the image in it, it falls back to the moving `:latest` tag and
+ * warns.
  */
 import type { Component } from './instance/types.js';
 /** The published image a component runs, whatever the service is named. */
@@ -21,10 +15,7 @@ export declare function installerImageName(component: Component): string;
 export declare function pinnedImageVersion(name: string, opts?: {
     filePath?: string;
 }): string | null;
-/**
- * Resolve `quay.io/kici-dev/<name>:<version>@sha256:<digest>` for an installer
- * image. Falls back to `:latest` (with a warning) when no recorded digest exists.
- */
+/** The digest-pinned installer image ref, else `:latest` with a warning. */
 export declare function resolveImageRef(name: string, opts?: {
     filePath?: string;
 }): string;

package/dist/cli/service/index.d.ts

@@ -1,11 +1,4 @@
-/**
- * Service management entry point.
- *
- * Re-exports all types and provides a factory function that returns
- * the correct ServiceManager implementation for the detected (or
- * specified) platform. Uses dynamic imports to avoid loading all
- * platform-specific code on every platform.
- */
+/** Service management entry point: re-exports and the per-platform ServiceManager factory. */
 export type { ServiceManager, ServiceConfig, LaunchSpec, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
 export { DEFAULT_RESTART_POLICY, SERVICE_TEXT } from './types.js';
 export { detectPlatform, isRoot, kiciConfigRoot, getConfigDir, getLogDir, getCacheDir, } from './platform-detect.js';
@@ -19,15 +12,6 @@ export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, }
 export { candidatePlatforms, listInstances, resolveInstance, resolveInstanceTarget, formatRefusal, InstanceNotFoundError, } from './instance/resolve.js';
 export type { ListedInstance, ResolveArgs, ListInstancesArgs, ResolveTargetArgs, ResolvedTarget, } from './instance/resolve.js';
 import type { ServiceManager, ServicePlatform } from './types.js';
-/**
- * Create a ServiceManager for the given platform.
- *
- * Uses dynamic imports so only the relevant platform code is loaded.
- * For example, on Linux only the systemd module is imported, not
- * Windows or launchd code.
- *
- * @param platform - Target platform (from detectPlatform() or --platform flag)
- * @returns The appropriate ServiceManager implementation
- */
+/** Dynamic imports load only the target platform's driver. */
 export declare function createServiceManager(platform: ServicePlatform): Promise<ServiceManager>;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/service/instance/index-file.d.ts

@@ -1,28 +1,21 @@
 /**
- * Instance index — a reconciled CACHE of all installed instances on the host.
- *
- * Lives at <kiciRoot>/instances.json, where kiciRoot is the name-agnostic
- * config root (~/.config/kici/ for user-level, /etc/kici/ for system). The
- * index is convenience: discovery is authoritative against the init system
- * (see resolve.ts#listInstances which reconciles this file against scans).
- *
- * Corrupt index → warn and treat as empty; the next install/uninstall
- * rewrites it cleanly.
+ * `<kiciRoot>/instances.json`: a reconciled CACHE of the host's installed
+ * instances. Discovery against the init system is authoritative
+ * (resolve.ts#listInstances reconciles this file against scans). A corrupt
+ * index warns and reads as empty; the next install/uninstall rewrites it.
  */
 import type { Component, IndexEntry } from './types.js';
-/** Resolve <kiciRoot>/instances.json. */
 export declare function indexPath(kiciRoot: string): string;
-/** Read the index. Missing or corrupt → []. */
+/** Missing or corrupt → []. */
 export declare function readIndex(kiciRoot: string): IndexEntry[];
-/** Overwrite the index. */
 export declare function writeIndex(kiciRoot: string, entries: IndexEntry[]): void;
 /**
- * Append an entry. Idempotent for an exact (component,name,instanceDir) match.
- * Throws on a (component,name) collision with a different instanceDir — the
- * caller must use a different name or pass --force to overwrite.
+ * Idempotent for an exact (component,name,instanceDir) match. Throws on a
+ * (component,name) collision at another instanceDir: the caller picks another
+ * name or passes --force.
  */
 export declare function appendIndexEntry(kiciRoot: string, entry: IndexEntry): void;
-/** Remove the matching entry (no-op when absent). */
+/** No-op when absent. */
 export declare function removeIndexEntry(kiciRoot: string, key: {
     component: Component;
     name: string;

package/dist/cli/service/instance/manifest.d.ts

@@ -1,56 +1,37 @@
 /**
- * Instance manifest — the single source of truth for a folder-anchored
- * service install. Written by `install` into the deploy folder, read by
- * every lifecycle command to reconstruct the ServiceConfig.
+ * Instance manifest: the single source of truth for a folder-anchored install.
+ * `install` writes it into the deploy folder; every lifecycle command rebuilds
+ * the ServiceConfig from it.
  */
 import type { Component, InstanceManifest } from './types.js';
 import type { LaunchSpec } from '../types.js';
-/** Per-component manifest filename. */
 export declare function manifestFilename(component: Component): string;
-/** Resolve the manifest path inside an instance directory. */
 export declare function manifestPath(instanceDir: string, component: Component): string;
-/**
- * Read the manifest for `component` from `instanceDir`.
- * Returns null when the file does not exist; throws on parse or schema errors.
- */
+/** Null when the file does not exist; throws on parse or schema errors. */
 export declare function readManifest(instanceDir: string, component: Component): InstanceManifest | null;
-/**
- * Write the manifest for `manifest.component` into `instanceDir`.
- * Returns the full path written.
- */
+/** Returns the path written. */
 export declare function writeManifest(instanceDir: string, manifest: InstanceManifest): string;
 /**
- * Read the running kici-admin's version from the orchestrator package.json.
- *
- * `process.env.npm_package_version` is only populated under `npm run` and is
- * undefined when kici-admin runs as a globally-installed binary, which is the
- * actual install path. Reading from the package.json on disk is the only
- * reliable source.
+ * The running kici-admin's version, from the orchestrator package.json on
+ * disk: `npm_package_version` is set only under `npm run`, never for the
+ * globally installed binary.
  */
 export declare function readKiciVersion(): string;
 /**
- * Resolve the `@kici-dev/<component>` package version that a {@link LaunchSpec}
- * will actually execute, by locating the component's entry script among the
- * spec's tokens and reading the version from the package.json that owns it.
- *
- * Returns null when no resolvable entry script is present (e.g. an opaque
- * `--binary` install) or the owning package.json is missing / name-mismatched.
- * This is what lets the npm-source upgrade refuse to report a version it can't
- * stand behind.
+ * The `@kici-dev/<component>` version a {@link LaunchSpec} executes, read from
+ * the package.json owning its entry script. Null when there is no entry script
+ * (an opaque `--binary` install) or the package.json is missing or
+ * name-mismatched, so the npm-source upgrade never reports an unverified version.
  */
 export declare function resolveVersionFromLaunchSpec(spec: LaunchSpec, component: Component): string | null;
 /**
- * The version of the launcher a service definition starts, or null when the
- * launch command does not show one.
- *
- * An npm-installed entry script names its version in its package.json
- * ({@link resolveVersionFromLaunchSpec}). A launcher under the instance's
- * install base resolves into the `<component>-<version>` folder an archive
- * upgrade extracted: through the `<component>` symlink on Linux and macOS, or
- * directly where Windows registers it. A `--binary` anywhere else shows none.
+ * The version of the launcher a service definition starts, or null. An npm
+ * entry script names it in its package.json ({@link resolveVersionFromLaunchSpec});
+ * a launcher under the install base resolves into its `<component>-<version>`
+ * folder (through the symlink on Linux and macOS, directly on Windows). A
+ * `--binary` anywhere else shows none.
  */
 export declare function resolveLauncherVersion(spec: LaunchSpec, component: Component, installBase: string): string | null;
-/** What {@link writeInstallManifest} wrote. */
 export interface InstallManifestWrite {
     file: string;
     manifest: InstanceManifest;
@@ -58,41 +39,60 @@ export interface InstallManifestWrite {
     warning?: string;
 }
 /**
- * Write the manifest `install` built into `instanceDir`.
- *
- * A first install writes `fresh` as it is. A re-install of the same instance
- * (the folder holds a readable manifest of this component and name) updates
- * that manifest: it keeps what the instance recorded over time — `createdAt`,
- * the `migrationHeads` the rollback schema guard reads, and any field a newer
- * CLI wrote — and takes every other field from `fresh`. Its `kiciVersion` is
- * the version of the launcher `launch` starts; when the launcher shows none,
- * the recorded version stands, because the CLI that ran `install` need not
- * be the version the service runs. A compose service runs the image its
- * compose file pins, whatever `launch` names, so a compose re-install records
- * the release of that image (`opts.digestRecordPath` overrides the digest
- * record it reads, for tests).
- *
- * A manifest that cannot be read, or that names another instance, is
- * replaced, and the result carries a warning.
+ * Write the manifest `install` built. A first install writes `fresh`. A
+ * re-install of the same instance (readable manifest, same component and name)
+ * keeps `createdAt`, the `migrationHeads` the rollback schema guard reads, and
+ * any field a newer CLI wrote, and takes the rest from `fresh`. `kiciVersion`
+ * is the version of the launcher `launch` starts, else the recorded one stands,
+ * because the CLI running `install` need not be the version the service runs.
+ * A compose re-install records the release of the image its compose file pins,
+ * whatever `launch` names (`opts.digestRecordPath` overrides the record, for
+ * tests). An unreadable manifest, or one naming another instance, is replaced
+ * with a warning.
  */
 export declare function writeInstallManifest(instanceDir: string, fresh: InstanceManifest, launch: LaunchSpec, opts?: {
     digestRecordPath?: string;
 }): InstallManifestWrite;
 /**
- * The global npm package + node runtime an npm-source upgrade must install
- * into, derived from a unit's launch spec. `owningPackage` is the top-level
- * global package whose ExecStart the unit runs — `kici-admin` when the
- * component is loaded through its nested node_modules, or `@kici-dev/<component>`
- * for a standalone install. `npmPath` is the npm co-located with the unit's
- * pinned node, so `npm install -g` with it lands in exactly the prefix
- * ExecStart resolves from, regardless of the shell's active node.
+ * Where an npm-source upgrade installs, from a unit's launch spec.
+ * `owningPackage` is the top-level global package ExecStart runs (`kici-admin`
+ * when the component loads through its nested node_modules, else
+ * `@kici-dev/<component>`). `globalPrefix` is the npm prefix the launch entry
+ * lives in; every npm call passes it as `--prefix`, because the caller's
+ * environment can name another one (`npx` exports `npm_config_prefix`).
+ * `npmInvocation` runs `npm-cli.js` with the pinned node when it sits beside
+ * that node, so a version-manager wrapper at `npmPath` (mise's reshim needs
+ * mise on PATH) is never started.
  */
 export interface NpmInstallTarget {
     nodeExecPath: string;
     npmPath: string;
     owningPackage: string;
+    globalPrefix: string;
+    npmInvocation: {
+        cmd: string;
+        preArgs: string[];
+    };
 }
+/**
+ * The resolution of a launch spec to an install target. `no-entry` covers an
+ * opaque `--binary` install and a path outside `node_modules`; `not-global`
+ * an entry under a local `node_modules` tree, whose prefix the unit's npm
+ * cannot install into with `-g`.
+ */
+export type NpmInstallResolution = {
+    ok: true;
+    target: NpmInstallTarget;
+} | {
+    ok: false;
+    reason: 'no-entry';
+} | {
+    ok: false;
+    reason: 'not-global';
+    entry: string;
+};
 export declare function resolveNpmInstallTarget(spec: LaunchSpec, component: Component, opts: {
     windows: boolean;
-}): NpmInstallTarget | null;
+    exists?: (p: string) => boolean;
+}): NpmInstallResolution;
 //# sourceMappingURL=manifest.d.ts.map