@cpajs/cpa 0.0.1-alpha-3 → 0.1.0-rc.2

package/dist/server/types.d.ts

@@ -15,6 +15,22 @@ export interface HomeOptions {
     /** Keep using the JWT's address instead of discovering cluster nodes (`-home-disable-cluster-discovery`). */
     disableClusterDiscovery?: boolean;
 }
+export interface ManagementOptions {
+    /** Management API key. Empty keys are rejected. */
+    key: string;
+    /**
+     * Write `management.allow-remote`, which lets non-loopback clients use the
+     * management API. Default `false`; ignored by `viaEnvironment`, which always
+     * enables remote access upstream.
+     */
+    allowRemote?: boolean;
+    /**
+     * Pass the key to CPA through `MANAGEMENT_PASSWORD` instead of writing a
+     * bcrypt hash into the managed config. Upstream treats that variable as
+     * enabling remote management and compares the key in plaintext.
+     */
+    viaEnvironment?: boolean;
+}
 interface CommonServerOptions {
     /** Use this executable instead of the bundled platform package. */
     binaryPath?: string;
@@ -23,10 +39,15 @@ interface CommonServerOptions {
      * directory. When omitted, a temporary directory is created and removed on stop.
      */
     stateDir?: string;
+    /** Management API key and how it reaches CPA. */
+    management?: ManagementOptions;
     /**
-     * Management key passed to CPA through the `MANAGEMENT_PASSWORD` environment
-     * variable, so it never touches disk. Note that upstream treats this variable
-     * as allowing remote management access regardless of `management.allow-remote`.
+     * Deprecated alias for `management: { key }`. It uses the safe default
+     * (bcrypt hash in the config, remote management disabled) and will be removed
+     * in a future release. Use `management.viaEnvironment` for the old
+     * `MANAGEMENT_PASSWORD` behaviour.
+     *
+     * @deprecated Use `management` instead.
      */
     managementKey?: string;
     /**
@@ -34,6 +55,22 @@ interface CommonServerOptions {
      * (`-local-model`). Explicit `models.*` config sources still win.
      */
     localModel?: boolean;
+    /**
+     * Start CPA through `cpa-launcher` so it cannot outlive this process, even
+     * when this process is killed with SIGKILL or crashes. Default `true`.
+     *
+     * - Linux: the launcher sets PR_SET_PDEATHSIG and execs CPA (no extra process).
+     * - macOS / BSD: the launcher stays as CPA's parent and stops it when this
+     *   process dies; `pid` is then the launcher's pid, and signals sent to it are
+     *   forwarded to CPA.
+     * - Windows: not needed; Node already kills child processes with their parent.
+     *
+     * The launcher ships next to the CPA binary in every platform package. With a
+     * custom `binaryPath` it is looked up next to that binary and then in an
+     * installed platform package; if none is found CPA is started directly and a
+     * notice is logged through `onLog`.
+     */
+    launcher?: boolean;
     /** Run as a node of a CPA Home control plane. Home mode disables the local management API. */
     home?: HomeOptions;
     /**
@@ -52,23 +89,39 @@ interface CommonServerOptions {
     onLog?: (log: LogLine) => void;
     /** Additional strings to redact from logs and errors. */
     redact?: readonly string[];
-    /** Default grace period for `stop()` before the process is killed. Default 10 000 ms. */
+    /** Default grace period for `stop()` before the process is killed. Ignored on Windows, where `stop()` terminates forcefully. Default 10 000 ms. */
     stopTimeoutMs?: number;
 }
 export interface StartWithConfigOptions extends CommonServerOptions {
     /**
-     * Native CPA configuration. It is written to `<stateDir>/config.yaml` on
-     * every start, replacing whatever CPA persisted there during the last run.
+     * Native CPA configuration.
+     *
+     * Written as YAML to `<stateDir>/config.yaml` only when that file does not
+     * exist. On later starts the existing file is reused, so changes made through
+     * the management API (or by CPA itself) survive a `stop()` / `startServer()`
+     * cycle. Set `overwriteConfig: true` to replace it with this object.
      */
     config?: CpaConfig;
     configPath?: never;
-    /** Bind host. Overrides `config.server.host`. Default `127.0.0.1`. */
+    /**
+     * Replace `<stateDir>/config.yaml` even when it already exists. Default
+     * `false`. When the existing file is kept, `config`, `host` and `port` are not
+     * applied and a message is emitted through `onLog`.
+     */
+    overwriteConfig?: boolean;
+    /** Bind host, when cpajs writes the managed file. Default `config.server.host`, else `127.0.0.1`. */
     host?: string;
-    /** Bind port. Overrides `config.server.port`. Default `0`, meaning a free port is picked. */
+    /** Bind port, when cpajs writes the managed file. Default `config.server.port`, else `0` (a free port is picked). */
     port?: number;
 }
 export interface StartWithConfigPathOptions extends CommonServerOptions {
-    /** Existing CPA config file, handed to CPA as-is. CPA may rewrite it (e.g. to hash `secret-key`). */
+    /**
+     * Existing CPA config file, handed to CPA as-is. CPA may rewrite it on
+     * startup: it hashes a plaintext `management.secret-key`, removes legacy
+     * keys that conflict with their v8 equivalents, and normalizes the layout.
+     * The file must set a fixed positive port; a missing or non-positive port
+     * makes CPA bind a random port it does not report.
+     */
     configPath: string;
     config?: never;
     host?: never;
@@ -80,9 +133,18 @@ export interface ExitResult {
     signal: NodeJS.Signals | null;
 }
 export interface StopOptions {
-    /** Grace period after the termination signal before the process is killed. */
+    /** Grace period after the termination signal before the process is killed. Ignored on Windows, where the process is terminated forcefully right away. */
     timeoutMs?: number;
 }
+export interface RestartOptions {
+    /**
+     * Grace period after the termination signal before the old process is killed.
+     * Defaults to `stopTimeoutMs`.
+     */
+    timeoutMs?: number;
+    /** Cancels the restart. The server is left stopped, like any other failed restart. */
+    signal?: AbortSignal;
+}
 export interface CpaServer {
     /** e.g. `http://127.0.0.1:8317`. Use as the client `baseUrl`. */
     readonly origin: string;
@@ -94,15 +156,27 @@ export interface CpaServer {
     readonly binaryPath: string;
     readonly configPath: string;
     readonly stateDir: string;
-    /** The management key given in the options, if any. */
-    readonly managementKey: string | undefined;
     readonly process: ChildProcess;
     /** Recent output lines (redacted), oldest first. */
     readonly recentLogs: readonly LogLine[];
-    /** Settles when the process exits, whether or not `stop()` was called. */
+    /**
+     * Settles when the process exits for good: on `stop()` or an unexpected exit.
+     * A restart stops one process and starts another, so it does not settle this.
+     */
     readonly exited: Promise<ExitResult>;
-    /** Terminates CPA gracefully, killing it after the grace period. Idempotent. */
+    /**
+     * Stops CPA. On POSIX it sends SIGTERM and then SIGKILL after the grace
+     * period. On Windows Node cannot deliver a graceful signal, so the process is
+     * terminated forcefully (there is no grace period and CPA is not asked to
+     * flush state or update auth files). Idempotent.
+     */
     stop(options?: StopOptions): Promise<ExitResult>;
+    /**
+     * Restarts CPA with the original options, reusing `origin`, `baseUrl`, `host`,
+     * `port`, `stateDir` and the existing config file. Concurrent calls share one
+     * operation. A failed or cancelled restart leaves the server stopped.
+     */
+    restart(options?: RestartOptions): Promise<void>;
 }
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cpajs/cpa",
-  "version": "0.0.1-alpha-3",
+  "version": "0.1.0-rc.2",
   "description": "Run the official CLIProxyAPI from JavaScript and talk to its v8 management API with a typed client",
   "license": "MIT",
   "author": "akarachen",
@@ -35,7 +35,11 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "cpa:source": "node scripts/fetch-source.ts",
     "cpa:build": "node scripts/build-binary.ts",
@@ -46,10 +50,13 @@
     "test:install": "node scripts/install-test.ts"
   },
   "dependencies": {
+    "bcryptjs": "^3.0.3",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.6.3",
     "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^5.0.5",
     "typescript": "^7.0.2",
     "vitest": "^5.0.5"
   },
@@ -58,28 +65,28 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@cpajs/darwin-x64": "0.0.1-alpha-3",
-    "@cpajs/darwin-arm64": "0.0.1-alpha-3",
-    "@cpajs/win32-x64": "0.0.1-alpha-3",
-    "@cpajs/win32-arm64": "0.0.1-alpha-3",
-    "@cpajs/win32-ia32": "0.0.1-alpha-3",
-    "@cpajs/linux-x64-gnu": "0.0.1-alpha-3",
-    "@cpajs/linux-arm64-gnu": "0.0.1-alpha-3",
-    "@cpajs/linux-x64-musl": "0.0.1-alpha-3",
-    "@cpajs/linux-arm64-musl": "0.0.1-alpha-3",
-    "@cpajs/linux-arm": "0.0.1-alpha-3",
-    "@cpajs/linux-ia32": "0.0.1-alpha-3",
-    "@cpajs/linux-riscv64": "0.0.1-alpha-3",
-    "@cpajs/linux-ppc64": "0.0.1-alpha-3",
-    "@cpajs/linux-s390x": "0.0.1-alpha-3",
-    "@cpajs/linux-loong64": "0.0.1-alpha-3",
-    "@cpajs/linux-mips": "0.0.1-alpha-3",
-    "@cpajs/linux-mipsel": "0.0.1-alpha-3",
-    "@cpajs/freebsd-x64": "0.0.1-alpha-3",
-    "@cpajs/freebsd-arm64": "0.0.1-alpha-3",
-    "@cpajs/freebsd-ia32": "0.0.1-alpha-3",
-    "@cpajs/openbsd-x64": "0.0.1-alpha-3",
-    "@cpajs/openbsd-arm64": "0.0.1-alpha-3",
-    "@cpajs/netbsd-x64": "0.0.1-alpha-3"
+    "@cpajs/darwin-x64": "0.1.0-rc.2",
+    "@cpajs/darwin-arm64": "0.1.0-rc.2",
+    "@cpajs/win32-x64": "0.1.0-rc.2",
+    "@cpajs/win32-arm64": "0.1.0-rc.2",
+    "@cpajs/win32-ia32": "0.1.0-rc.2",
+    "@cpajs/linux-x64-gnu": "0.1.0-rc.2",
+    "@cpajs/linux-arm64-gnu": "0.1.0-rc.2",
+    "@cpajs/linux-x64-musl": "0.1.0-rc.2",
+    "@cpajs/linux-arm64-musl": "0.1.0-rc.2",
+    "@cpajs/linux-arm": "0.1.0-rc.2",
+    "@cpajs/linux-ia32": "0.1.0-rc.2",
+    "@cpajs/linux-riscv64": "0.1.0-rc.2",
+    "@cpajs/linux-ppc64": "0.1.0-rc.2",
+    "@cpajs/linux-s390x": "0.1.0-rc.2",
+    "@cpajs/linux-loong64": "0.1.0-rc.2",
+    "@cpajs/linux-mips": "0.1.0-rc.2",
+    "@cpajs/linux-mipsel": "0.1.0-rc.2",
+    "@cpajs/freebsd-x64": "0.1.0-rc.2",
+    "@cpajs/freebsd-arm64": "0.1.0-rc.2",
+    "@cpajs/freebsd-ia32": "0.1.0-rc.2",
+    "@cpajs/openbsd-x64": "0.1.0-rc.2",
+    "@cpajs/openbsd-arm64": "0.1.0-rc.2",
+    "@cpajs/netbsd-x64": "0.1.0-rc.2"
   }
 }

package/src/client/resources/oauth.ts

@@ -9,7 +9,8 @@ import type {
   VertexImportResponse,
 } from '../types/oauth.ts';
 import type { SIWCStatusResponse } from '../types/credentials.ts';
-import type { RequestOptions, Transport } from '../transport.ts';
+import { CpaAbortError } from '../errors.ts';
+import { managementUrl, type RequestOptions, type Transport } from '../transport.ts';
 import type { CredentialContent, CredentialSelector } from './credentials.ts';
 
 export interface WaitForOAuthOptions extends RequestOptions {
@@ -38,23 +39,20 @@ export class OAuthResource {
     return (await this.#t.request<OAuthStatusResponse>({ ...options, method: 'GET', path: '/oauth/status', query: { state } })).data;
   }
 
-  /** Polls {@link status} until the session leaves `wait`. Abort with `signal`. */
+  /**
+   * Polls {@link status} until the session leaves `wait`. Abort with `signal`
+   * (for an overall limit use `AbortSignal.timeout()`); cancellation always
+   * rejects with `CpaAbortError`, whether it happens during a request or between polls.
+   */
   async waitForCompletion(state: string, options: WaitForOAuthOptions = {}): Promise<Exclude<OAuthStatusResponse, { status: 'wait' }>> {
     const { intervalMs = 2_000, ...requestOptions } = options;
+    const url = managementUrl(this.#t.baseUrl, '/oauth/status');
+    url.searchParams.set('state', state);
+    const target = { method: 'GET', url: url.toString() };
     while (true) {
       const result = await this.status(state, requestOptions);
       if (result.status !== 'wait') return result;
-      await new Promise<void>((resolve, reject) => {
-        const timer = setTimeout(resolve, intervalMs);
-        requestOptions.signal?.addEventListener(
-          'abort',
-          () => {
-            clearTimeout(timer);
-            reject(requestOptions.signal!.reason);
-          },
-          { once: true },
-        );
-      });
+      await abortableDelay(intervalMs, requestOptions.signal, target);
     }
   }
 
@@ -103,3 +101,20 @@ export class OAuthResource {
     return (await this.#t.request<SIWCStatusResponse>({ ...options, method: 'GET', path: '/oauth/siwc/status', query: { ...selector } })).data;
   }
 }
+
+/** Waits `ms`, rejecting with `CpaAbortError` if `signal` aborts; never leaves a listener behind. */
+function abortableDelay(ms: number, signal: AbortSignal | undefined, target: { method: string; url: string }): Promise<void> {
+  const aborted = () => new CpaAbortError(`${target.method} ${target.url} was aborted`, target, { cause: signal!.reason });
+  if (signal?.aborted) return Promise.reject(aborted());
+  return new Promise<void>((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(aborted());
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}

package/src/client/transport.ts

@@ -163,6 +163,8 @@ export class Transport {
     if (body !== undefined) init.body = body;
 
     const responseType = req.responseType ?? 'json';
+    // Set once a Response is handed to the caller, who then owns reading its body.
+    let handedOff = false;
     try {
       let response: Response;
       try {
@@ -175,6 +177,7 @@ export class Transport {
         throw new CpaHttpError(target, response, await guard(response.text()));
       }
       if (responseType === 'response') {
+        handedOff = true;
         return { data: response as T, status: response.status, headers: response.headers };
       }
       if (responseType === 'blob') {
@@ -194,9 +197,10 @@ export class Transport {
       }
       throw classify(error);
     } finally {
-      // For `response`, the caller reads the body; the timeout covers the headers only,
-      // while the caller's own signal keeps working through the request's signal.
-      if (responseType === 'response') clearTimeout(timer);
+      // A handed-off Response is read by the caller: the timeout covered the headers
+      // only, and the caller's signal must keep cancelling the body, so its listener
+      // stays until that signal aborts. Every other outcome releases everything.
+      if (handedOff) clearTimeout(timer);
       else release();
     }
   }

package/src/server/args.ts

@@ -26,7 +26,7 @@ const MANAGED_FLAGS: Record<string, string> = {
   'local-model': 'localModel',
   'home-jwt': 'home.jwt',
   'home-disable-cluster-discovery': 'home.disableClusterDiscovery',
-  password: 'managementKey',
+  password: 'management.key',
 };
 
 function flagName(arg: string): string | undefined {

package/src/server/binary.ts

@@ -2,7 +2,7 @@ import { accessSync, chmodSync, constants, existsSync, readdirSync, statSync } f
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { CpaBinaryError } from './errors.ts';
-import { TARGETS, UNSUPPORTED_PLATFORMS, binaryName, packageName, type Target } from './targets.ts';
+import { LAUNCHER_NAME, TARGETS, UNSUPPORTED_PLATFORMS, binaryName, packageName, type Target } from './targets.ts';
 
 const require = createRequire(import.meta.url);
 
@@ -126,3 +126,48 @@ export function resolveBinary(options: { binaryPath?: string; platform?: HostPla
       'make sure your lockfile was not created on another platform without it, or pass binaryPath.',
   );
 }
+
+/** How the launcher keeps CPA from outliving this process. */
+export type LauncherMode = 'exec' | 'supervise';
+
+export interface ResolvedLauncher {
+  path: string;
+  /**
+   * `exec` (Linux): the launcher sets PR_SET_PDEATHSIG and becomes CPA.
+   * `supervise` (macOS, BSD): the launcher stays as CPA's parent and stops it
+   * when its stdin pipe from this process closes.
+   */
+  mode: LauncherMode;
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Finds `cpa-launcher` for a CPA binary: next to the binary first (platform
+ * packages and local builds keep both in one directory), then in an installed
+ * platform package. Returns undefined on Windows, where Node already places
+ * child processes in a job object that is closed (and its processes killed)
+ * when this process exits.
+ */
+export function resolveLauncher(cpaPath: string, platform: HostPlatform = currentPlatform()): ResolvedLauncher | undefined {
+  if (platform.os === 'win32') return undefined;
+  const mode: LauncherMode = platform.os === 'linux' ? 'exec' : 'supervise';
+  const candidates = [join(dirname(cpaPath), LAUNCHER_NAME)];
+  for (const target of candidateTargets(platform)) {
+    try {
+      candidates.push(join(dirname(require.resolve(`${packageName(target)}/package.json`)), 'bin', LAUNCHER_NAME));
+    } catch {
+      // Package not installed.
+    }
+  }
+  const path = candidates.find(isExecutable);
+  return path === undefined ? undefined : { path, mode };
+}