@kici-dev/orchestrator 0.11.0 → 0.12.0

package/dist/cli/commands/workflow.d.ts

@@ -2,10 +2,9 @@
  * Workflow registration commands for kici-admin.
  *
  * Provides operator-facing read access to the workflow_registrations table
- * via the orchestrator's admin HTTP API. This is the dogfooded replacement
- * for "let me just psql the registration table" — every CLI subcommand here
- * goes through AdminApiClient and the existing /api/v1/admin/registrations
- * route.
+ * via the orchestrator's admin HTTP API. Use it instead of querying the
+ * registration table with psql: every CLI subcommand here goes through
+ * AdminApiClient and the existing /api/v1/admin/registrations route.
  *
  *   workflow list                List registered workflows (table or JSON)
  *

package/dist/cli/open-browser.d.ts

@@ -5,7 +5,7 @@
  * blocked launcher) just falls back to copy-paste.
  *
  * `KICI_BROWSER_CMD` overrides the launcher: `none` suppresses it entirely
- * (E2E / headless capture), any other value is run with `{url}` substituted —
+ * (automated tests / headless capture), any other value is run with `{url}` substituted —
  * mirroring the `kici login` convention.
  */
 export declare function openBrowserBestEffort(url: string): void;

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

@@ -33,4 +33,22 @@ export declare function resolveServiceExecutable(opts: {
     nodePath: string;
     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.
+ */
+export declare function resolveServerScript(specifier: string, component: ServerComponent, resolve: ModuleResolver | undefined): string;
+/**
+ * Refuse an install without `--binary` on a kici-admin that cannot resolve
+ * installed packages, before the wizard runs or any file is written.
+ */
+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/image-digests.d.ts

@@ -11,6 +11,16 @@
  * 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).
  */
+import type { Component } from './instance/types.js';
+/** The published image a component runs, whatever the service is named. */
+export declare function installerImageName(component: Component): string;
+/**
+ * The release {@link resolveImageRef} pins `name` at, or null when it falls
+ * back to the moving `:latest` tag.
+ */
+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.

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

@@ -7,12 +7,14 @@
  * platform-specific code on every platform.
  */
 export type { ServiceManager, ServiceConfig, LaunchSpec, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
-export { DEFAULT_RESTART_POLICY } from './types.js';
+export { DEFAULT_RESTART_POLICY, SERVICE_TEXT } from './types.js';
 export { detectPlatform, isRoot, kiciConfigRoot, getConfigDir, getLogDir, getCacheDir, } from './platform-detect.js';
 export { resolveUserLevel, type PrivilegeOpts } from './privilege.js';
+export { restrictEnvFileAccess } from './windows-acl.js';
+export { ENV_FILE_LOADER_EXPORT, envFileRefusal, launchReadsEnvFile, launchedRelease, } from './windows-env-file.js';
 export type { Component, InstanceManifest, IndexEntry, ResolveOptions, ResolvedInstance, } from './instance/types.js';
 export { COMPONENTS, isComponent } from './instance/types.js';
-export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, resolveNpmInstallTarget, type NpmInstallTarget, } from './instance/manifest.js';
+export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, resolveLauncherVersion, writeInstallManifest, type InstallManifestWrite, resolveNpmInstallTarget, type NpmInstallTarget, } from './instance/manifest.js';
 export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, } from './instance/index-file.js';
 export { candidatePlatforms, listInstances, resolveInstance, resolveInstanceTarget, formatRefusal, InstanceNotFoundError, } from './instance/resolve.js';
 export type { ListedInstance, ResolveArgs, ListInstancesArgs, ResolveTargetArgs, ResolvedTarget, } from './instance/resolve.js';

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

@@ -39,6 +39,45 @@ export declare function readKiciVersion(): string;
  * stand behind.
  */
 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.
+ */
+export declare function resolveLauncherVersion(spec: LaunchSpec, component: Component, installBase: string): string | null;
+/** What {@link writeInstallManifest} wrote. */
+export interface InstallManifestWrite {
+    file: string;
+    manifest: InstanceManifest;
+    /** Set when the folder held a manifest the install replaced instead of updating. */
+    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.
+ */
+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

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

@@ -18,8 +18,24 @@ export declare class LaunchdServiceManager implements ServiceManager {
     private label;
     /** Resolve the log directory based on service level. */
     private logDir;
-    /** Resolve the plist file path based on service level. */
-    private plistPath;
+    /** The directory launchd loads this service level's plists from. */
+    private plistDir;
+    /** The job `install` writes: `dev.kici.<name>`. */
+    private installJob;
+    /**
+     * An installed job for this name under another label: a `com.kici.<name>`
+     * plist, or a plist named after the service itself — each one `list()`
+     * reports as this instance. Only a plist that carries the KiCI component
+     * marker counts, and the job is addressed by the Label the plist declares.
+     */
+    private otherLabelJob;
+    /**
+     * The job a lifecycle command acts on: the `dev.kici.<name>` plist when it
+     * is installed, otherwise a job this name was installed under with another
+     * label, so every instance `list()` reports can be stopped, started and
+     * removed. With neither installed, the `dev.kici.<name>` job.
+     */
+    private resolveJob;
     /** Parse a .env file into key-value pairs. */
     private parseEnvFile;
     /** Escape XML special characters. */
@@ -41,20 +57,29 @@ export declare class LaunchdServiceManager implements ServiceManager {
      * domain from the plist's filesystem location, but they fail silently on
      * headless macOS hosts where no GUI session exists (the `gui/<uid>` domain
      * is not available without a console login). The modern `bootstrap` /
-     * `bootout` / `kickstart` / `kill` verbs take the domain explicitly, so a
+     * `bootout` / `kickstart` / `print` verbs take the domain explicitly, so a
      * system-level LaunchDaemon loads regardless of whether anyone is logged
      * in at the console — exactly what we need for headless deploy targets.
      */
     private domain;
-    /** `<domain>/<label>` — the target string for kickstart/kill/print/enable. */
+    /** `<domain>/<label>` — the target string for bootout/kickstart/print. */
     private domainTarget;
-    /** Is the service currently loaded in its target domain? */
+    /**
+     * `launchctl print <domain>/<label>`: the job's description while it is
+     * loaded, or null when launchd reports it not loaded. Unlike `launchctl
+     * list`, which lists only the caller's own domain, this reads a system
+     * daemon without root. Any other failure throws, so a job that could not be
+     * inspected is never mistaken for a stopped one.
+     */
+    private printJob;
+    /** Is the job currently loaded in its target domain? */
     private isLoaded;
     install(config: ServiceConfig): Promise<void>;
     /**
-     * Poll until the service is no longer loaded in its target domain, or a
-     * short deadline elapses. `launchctl bootout` is asynchronous — it returns
-     * before launchd has finished releasing the service — so a bootstrap issued
+     * Poll until the job is no longer loaded in its target domain, or the
+     * deadline elapses. Resolves true once the job has left the domain,
+     * false on timeout. `launchctl bootout` is asynchronous — it returns before
+     * launchd has finished releasing the job — so a bootstrap issued
      * immediately afterward races the teardown and fails with EIO. Waiting for
      * the unload to complete closes that race for the common case; the residual
      * window is covered by bootstrapWithRetry.
@@ -64,13 +89,23 @@ export declare class LaunchdServiceManager implements ServiceManager {
      * Bootstrap into the target domain, retrying on the transient EIO
      * ("5: Input/output error") launchd returns when a just-removed service has
      * not finished tearing down. A genuine, non-transient failure (bad plist,
-     * permission denied) is re-thrown on the first attempt. If a stale instance
-     * reappears between attempts, it is booted out before the next try.
+     * permission denied) is re-thrown on the first attempt.
+     *
+     * launchd answers a bootstrap of a job that is already loaded with the same
+     * EIO. With `replaceLoaded` (install, which just wrote a new plist) such a
+     * job is booted out before the next try. Without it (start), a job that
+     * another caller loaded meanwhile is the outcome start wanted: RunAtLoad has
+     * started it, so the call succeeds and leaves it running.
      */
     private bootstrapWithRetry;
     uninstall(config: ServiceConfig): Promise<void>;
     start(config: ServiceConfig): Promise<void>;
     stop(config: ServiceConfig): Promise<void>;
+    /**
+     * Boot the job out of its domain and wait until launchd has finished the
+     * teardown. Does nothing when no job is loaded.
+     */
+    private unload;
     restart(config: ServiceConfig): Promise<void>;
     status(config: ServiceConfig): Promise<ServiceStatus>;
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;

package/dist/cli/service/shutdown-grace.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How long an init system waits for a KiCI service to shut down.
+ */
+import type { ServiceConfig } from './types.js';
+/**
+ * Seconds an init system must wait after SIGTERM before it SIGKILLs the service.
+ *
+ * The runtime defaults are shorter than either component's own graceful-shutdown
+ * budget: Compose waits 10s, launchd's default ExitTimeOut is 5s, and shawl's
+ * default `--stop-timeout` on Windows is 3s. A teardown that
+ * takes longer is killed partway through: the orchestrator never broadcasts
+ * `peer.leaving` and never closes its agent sockets, and the agent never
+ * finishes draining. That window is reached exactly when it matters most — the
+ * orchestrator's scaler stops each managed agent with its own grace, so an
+ * orchestrator with agents in flight routinely needs more than 10s.
+ *
+ * Each value is its component's force-exit budget plus headroom, so the
+ * process always reaches its own timer first and the runtime's kill stays the
+ * last resort it is meant to be:
+ * - orchestrator: 30s (`setupGracefulShutdown` default) plus up to 2s of log
+ *   file flush -> 45s
+ * - agent: 10s plus a ~1s abort delay in its `onForceExit` -> 20s
+ *
+ * An unrecognised component gets the larger value: over-waiting costs a few
+ * seconds on shutdown, under-waiting corrupts it.
+ */
+export declare function shutdownGraceSeconds(config: ServiceConfig): number;
+/**
+ * Seconds a `stop` waits for the init system to report the service stopped.
+ *
+ * The init system kills the process once its grace elapses, so a service still
+ * running after the grace plus this margin is hung, not slow.
+ */
+export declare function stopWaitSeconds(config: ServiceConfig): number;
+//# sourceMappingURL=shutdown-grace.d.ts.map

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

@@ -20,6 +20,15 @@ export interface RestartPolicy {
 }
 /** Default restart policy: backoff 1s, 5s, 15s, 30s; max 5 failures in 5 minutes. */
 export declare const DEFAULT_RESTART_POLICY: RestartPolicy;
+/**
+ * The display name and description a component's service is registered with.
+ * `install` and every upgrade that registers a service again use it, so an
+ * upgraded registration carries the same text as a fresh one.
+ */
+export declare const SERVICE_TEXT: Record<'orchestrator' | 'agent', {
+    displayName: string;
+    description: string;
+}>;
 /** Configuration for installing a service. */
 export interface ServiceConfig {
     /** Service identifier (e.g., "kici-orchestrator"). */

package/dist/cli/service/windows-acl.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Restricting a Windows service's env file to the service account and to
+ * Administrators.
+ *
+ * Node maps a file mode onto Windows by toggling the read-only attribute and
+ * changes no ACL, so ENV_FILE_MODE protects nothing there. The instance folder
+ * under C:\ProgramData\kici\ inherits read access for BUILTIN\Users from
+ * C:\ProgramData. Its ACL is replaced with full control for LocalSystem (the
+ * account the shawl service runs as) and Administrators, inherited by
+ * everything created in it: the env file, the temporary file a secure write
+ * stages it through, and the service logs are unreadable to other accounts
+ * from the moment they exist.
+ *
+ * Every call passes `/L` and none recurses, so icacls acts on the folder and on
+ * the env file themselves and never on what a link there points at. A
+ * recursive `/reset` or `/setowner` descends into the target of a junction or
+ * of a symbolic link, even with `/L`, and rewrites the ACL of the files there.
+ * The new folder ACL still reaches every entry that inherits from the folder.
+ */
+/** NT AUTHORITY\SYSTEM, the account a shawl service runs as. */
+export declare const LOCAL_SYSTEM_SID = "S-1-5-18";
+/** BUILTIN\Administrators. */
+export declare const ADMINISTRATORS_SID = "S-1-5-32-544";
+/** Runs `icacls` with the given arguments; throws when it fails. */
+export type IcaclsRunner = (args: string[]) => void;
+/**
+ * The icacls arguments that remove every inherited ACE from `dir` and grant
+ * full control, inherited by files and folders, to LocalSystem and
+ * Administrators. SIDs rather than names, so a localized Windows resolves them.
+ */
+export declare function restrictDirArgs(dir: string): string[];
+/** The icacls arguments that reset `file` to inherit only from its folder. */
+export declare function resetFileArgs(file: string): string[];
+/**
+ * Restrict the folder that holds `envFilePath`, then reset an existing env
+ * file to inherit only from it, which also drops any explicit ACE on the file.
+ * Run it before the first secret is written into the folder.
+ */
+export declare function restrictEnvFileAccess(envFilePath: string, run?: IcaclsRunner, exists?: (filePath: string) => boolean): void;
+//# sourceMappingURL=windows-acl.d.ts.map

package/dist/cli/service/windows-env-file.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Whether a Windows service launch runs a release that reads KICI_ENV_FILE.
+ *
+ * A Windows service is registered with the path of its env file in
+ * KICI_ENV_FILE, never with the values in the file: any local account reads the
+ * command line of a service with `sc.exe qc`. A release from before
+ * KICI_ENV_FILE ignores the path and starts without its configuration, and the
+ * only registration that would run it puts the values back on the command line.
+ * So every command that registers a Windows service, or switches one to another
+ * release, refuses such a release before it changes anything.
+ */
+/**
+ * The `@kici-dev/shared` export that loads the env file KICI_ENV_FILE names. A
+ * release publishes it, and imports it first in each entry, only when it reads
+ * KICI_ENV_FILE.
+ */
+export declare const ENV_FILE_LOADER_EXPORT = "./load-service-env-file";
+/**
+ * The file that names a launch's release: the npm entry among its arguments,
+ * or else the executable itself.
+ */
+export declare function launchedRelease(launch: {
+    executablePath: string;
+    args?: string[];
+}): string;
+/**
+ * Whether the process a Windows service launch starts reads KICI_ENV_FILE.
+ *
+ * A KiCI package runs as `<dir>\<name>.cmd` beside its bundle
+ * `<dir>\lib\<name>.cjs`, which names KICI_ENV_FILE when the release reads it.
+ * An npm install runs node with the `@kici-dev/<component>/dist/<entry>.js`
+ * entry, which then imports the env-file loader. Any other launch, such as a
+ * batch file with no KiCI bundle beside it or a custom executable, is taken to
+ * read it.
+ */
+export declare function launchReadsEnvFile(launch: {
+    executablePath: string;
+    args?: string[];
+}): boolean;
+/**
+ * Why a Windows service may not run `release`, a release from before
+ * KICI_ENV_FILE, and what the operator can do instead.
+ */
+export declare function envFileRefusal(release: string, envFilePath: string): string;
+//# sourceMappingURL=windows-env-file.d.ts.map

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

@@ -30,6 +30,8 @@ export declare class WindowsServiceManager implements ServiceManager {
      * not exist; exit 0 means it exists (possibly pending-delete).
      */
     private serviceExists;
+    /** The service's STATE code from `sc.exe query`, or undefined when the query fails. */
+    private queryStateCode;
     install(config: ServiceConfig): Promise<void>;
     uninstall(config: ServiceConfig): Promise<void>;
     start(config: ServiceConfig): Promise<void>;
@@ -39,6 +41,17 @@ export declare class WindowsServiceManager implements ServiceManager {
     logs(config: ServiceConfig, _options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
+    /**
+     * The command line a service is registered with.
+     *
+     * `sc.exe qc` answers most registrations, but it fails (error 1734) once the
+     * line is longer than about 4000 characters, as an older CLI's registration
+     * with every env-file value on it can be. It also prints in the console code
+     * page, so a path outside ASCII, such as one under the profile of a user
+     * named Jürgen, decodes to U+FFFD. In either case the registry value it reads
+     * (`ImagePath`) is read through PowerShell, printed as UTF-8.
+     */
+    private registeredCommandLine;
     readLaunchSpec(config: ServiceConfig): Promise<LaunchSpec | null>;
 }
 //# sourceMappingURL=windows.d.ts.map