@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/dist/components/Application.d.ts

@@ -11,6 +11,25 @@ interface ApplicationConfig {
         allowInstallScripts?: boolean;
     };
     credentials?: CredentialReference[];
+    /**
+     * Databases this application gets a private fork of (harper#642), declared HERE — on the
+     * application's root-config entry, alongside `host` and `urlPath` — because which databases an
+     * application forks is a deployment decision, not something the application checks in. Declaring
+     * it in the application's own config.yaml is refused rather than ignored.
+     *
+     * `true` forks every database on the instance except `system` -- a snapshot of what exists when
+     * this application loads, not a standing subscription: a database created afterward is not
+     * retroactively branched.
+     *
+     * The fork is durable: it lives at a path derived from the application and database names, is
+     * adopted again on restart, and is invisible to other applications.
+     *
+     * The application must reach its data through `import { databases } from 'harper'`. The bare
+     * `databases`/`tables` globals are shared process-wide by the default `vm-current-context` loader
+     * and cannot be scoped, so an application that uses them reads and writes the BASE — silently.
+     * Per-application globals are a property of thread-level isolation, not of branching.
+     */
+    branchedDatabases?: string[] | true;
     [key: string]: unknown;
 }
 export declare class InvalidPackageIdentifierError extends TypeError {
@@ -28,10 +47,18 @@ export declare class InvalidInstallTimeoutError extends TypeError {
 export declare class InvalidCredentialsPropertyError extends TypeError {
     constructor(applicationName: string, credentials: unknown);
 }
+export declare class InvalidBranchedDatabasesError extends TypeError {
+    constructor(applicationName: string, detail: string);
+}
 export declare class InvalidCredentialEntryError extends TypeError {
     constructor(applicationName: string);
 }
 export declare function assertApplicationConfig(applicationName: string, applicationConfig: Record<'package', unknown> & Record<string, unknown>): asserts applicationConfig is ApplicationConfig;
+/**
+ * A branch that cannot be honoured fails the application's load: falling back would hand it the
+ * shared database it asked not to have, with no signal that it happened.
+ */
+export declare function assertBranchedDatabases(applicationName: string, value: unknown): void;
 /**
  * Returns true when npm/git stderr indicates an SSH authentication failure —
  * git exits 128 with the standard "could not read" message, or the SSH layer
@@ -58,6 +85,7 @@ interface GitReference {
  */
 export declare function parseGitReference(packageIdentifier: string): GitReference | null;
 export declare const ASIDE_STAGING_DIR = ".deploy-aside";
+export declare const DEPLOY_STAGING_DIR = ".deploy-staging";
 type ExtractionTransaction = {
     commit(): Promise<void>;
     rollback(): Promise<void>;
@@ -69,6 +97,8 @@ type InstalledPackageMetadata = {
     hasLockfile: boolean;
     hasInstallableDependencies: boolean;
 };
+export declare function packageHasProductionInstallWork(packageJSON: any): boolean;
+export declare function packageHasAutomaticInstallWork(packageJSON: any): boolean;
 export declare function readInstalledPackageMetadata(directory: string): Promise<InstalledPackageMetadata>;
 export declare function installedPackageMetadataEqual(previous: InstalledPackageMetadata, current: InstalledPackageMetadata): boolean;
 export declare function installedRuntimeChanged(previous: InstalledPackageMetadata, current: InstalledPackageMetadata, installationIsOpaque: boolean): boolean;
@@ -83,17 +113,93 @@ export declare function installedRuntimeChanged(previous: InstalledPackageMetada
  * threads by the preparation lock below.
  */
 export declare function extractApplication(application: Application, deferCommit?: boolean): Promise<ExtractionTransaction | undefined>;
+/** Where a candidate build lives: `<root>/.deploy-staging/<deploymentId>/<component>`. */
+export declare function candidateApplicationPath(componentDirPath: string, deploymentId: string): string;
+export declare function makeRollbackPlaceholderMovable(applicationDirPath: string, placeholderIdentity: {
+    dev: bigint;
+    ino: bigint;
+} | undefined): Promise<void>;
+/**
+ * The components a deployment's evidence implicates, when its journal and its ownership sidecar disagree
+ * about whose it is — or `undefined` when there is no disagreement to act on.
+ *
+ * A sidecar that cannot answer is NOT disagreement: the journal names its own component and can settle it,
+ * so an unreadable sidecar must not block that. Only a sidecar that reads and names something else is the
+ * wedge, and then BOTH names are returned, sidecar first, because both are stuck — see
+ * `splitAttributionError`.
+ *
+ * Separated from either call site so the decision is testable on its own: the paths that reach it include
+ * one that requires a journal to appear between two reads under a lock, which no test can stage.
+ */
+export declare function splitAttributionOwners(journalOwner: string, sidecarOwner: string | undefined): [string, string] | undefined;
 /**
- * Install an application to its relative `application.dirPath` using either a
- * configured `application.install` command, a derived package manager from the
- * application's `package.json#devEngines`, or falling back to the default
- * package manager, `npm`.
+ * Components that on-disk evidence says were left in a state nobody settled — determined READ-ONLY, so any
+ * thread can reach the same verdict.
  *
- * Will return early if `node_modules` already exists within the `application.dirPath`
+ * Recovery runs on the main thread only, but the components it could not settle still have to be failed
+ * closed on the workers that actually serve them, and a worker cannot be handed main's verdict: it boots
+ * through its own `loadRootComponents(true)`, potentially before main finished. Recovery deliberately KEEPS
+ * the evidence for anything it could not settle, so a worker can read it instead of being told.
  *
- * This method may be called from any Harper thread as part of a serialized preparation.
+ * Only unambiguous evidence counts. A well-formed journal is NOT evidence — every healthy deploy has one
+ * in flight — so this reports a journal that cannot be read at all (corrupt, unknown version, or naming
+ * something other than its own deployment), which no in-flight deploy ever produces.
  */
-export declare function installApplication(application: Application): Promise<void>;
+export declare function unsettleableComponentsFromDisk(componentsRootDirPath: string): Promise<Map<string, Error>>;
+/**
+ * Settle activations a crash interrupted, before anything loads. Runs at startup on main and on every
+ * worker — a worker can be respawned mid-activation, long after main's pass.
+ *
+ * Returns failures keyed by COMPONENT so the caller can fail exactly those closed and still load every
+ * healthy sibling — a single unreadable journal must not take down the whole node, and must not let a
+ * component load over state nobody reconciled.
+ *
+ */
+export declare function recoverInterruptedActivations(componentsRootDirPath: string): Promise<Map<string, Error>>;
+export declare function markCandidateComplete(componentDirPath: string, deploymentId: string, componentName: string): Promise<void>;
+/**
+ * Make a built and validated candidate live, as one compensating transaction over two effects: the live tree
+ * moves aside, then the candidate takes its place. Root config is NOT one of them — it is still published
+ * before the build, unchanged, and making it transactional is tracked separately (#2315).
+ *
+ * The `complete` marker and the activation journal are written and fsynced BEFORE the first rename, so a
+ * crash anywhere below is recoverable — see `settleInterruptedActivation` for the state matrix. The second
+ * rename is the COMMIT POINT: nothing after it may compensate, because the live path holds the candidate and
+ * renaming the aside back over it cannot succeed.
+ */
+export declare function activateCandidateApplication(application: Application, deploymentId: string): Promise<void>;
+/**
+ * Build a deploy candidate at `.deploy-staging/<deploymentId>/<component>`, leaving the live tree
+ * completely untouched — this is what lets the previous version keep serving through the clone, the
+ * extraction and the dependency install.
+ *
+ * Failure needs no compensation, which is the whole point: nothing about the live component was modified,
+ * so the abandoned candidate is simply removed and the error propagates.
+ */
+export declare function buildCandidateApplication(application: Application, deploymentId: string): Promise<string>;
+export declare function recoverInterruptedComponentExtractions(componentsRootDirPath: string): Promise<Map<string, Error>>;
+export declare function recoverInterruptedComponentExtraction(componentsRootDirPath: string, componentName: string, waitForPreparation?: boolean, waitTimeoutMs?: number): Promise<void>;
+export declare function retireComponentExtractionStaging(componentDirPath: string, componentName?: string, componentLogger?: Logger): Promise<void>;
+export declare function dropComponentDirectory(componentDirPath: string, componentName?: string, componentLogger?: Logger): Promise<void>;
+/**
+ * The one definition of how Harper invokes a package manager to install dependencies; every npm
+ * entry point composes its arguments here rather than assembling its own.
+ */
+export declare function packageManagerInstallArguments(packageManagerName: string, allowInstallScripts: boolean, force?: boolean): string[];
+/**
+ * Install a component's dependencies into `buildDirPath` — the live path, or a candidate under
+ * `.deploy-staging`. Explicit rather than repointing `application.dirPath`, which is read after preparation
+ * too and would name a vanished directory if any failure path skipped the restore.
+ *
+ * Uses a configured `application.install` command, a package manager derived from the application's
+ * `package.json#devEngines`, or the default, `npm`. Returns early when `node_modules` already exists or
+ * when the manifest has no automatic install work. An explicitly selected non-npm manager is always
+ * allowed to inspect its own workspace configuration, even when the root manifest has no production
+ * dependencies.
+ *
+ * May be called from any Harper thread as part of a serialized preparation.
+ */
+export declare function installApplication(application: Application, buildDirPath?: string): Promise<void>;
 /**
  * Callback invoked once per complete line of install stdout/stderr from
  * `nonInteractiveSpawn`. Threaded through `installApplication` to the underlying spawn
@@ -119,6 +225,7 @@ export declare class Application {
     name: string;
     payload?: Buffer | string | Readable;
     packageIdentifier?: string;
+    readonly packLocalDirectory: boolean;
     install?: {
         command?: string;
         timeout?: number;
@@ -141,12 +248,8 @@ export declare class Application {
     cleanupGitCredentialSession(): Promise<void>;
     cleanupTransientNpmrc(): Promise<void>;
 }
-/**
- * Based on an old implementation for a method called `getPkgPrefix()` that was used
- * during the installation process in order to actually resolve what the user specifies for a
- * component matching some of npm's package resolution rules.
- */
 export declare function derivePackageIdentifier(packageIdentifier: string): string;
+export declare function shouldPackLocalDirectory(packageIdentifier: string | undefined, platform?: NodeJS.Platform): boolean;
 /**
  * Extract and install the specified application.
  *
@@ -163,7 +266,16 @@ export declare function derivePackageIdentifier(packageIdentifier: string): stri
  * @param application The application to prepare.
  * @returns A promise that resolves when all preparation steps complete.
  */
-export declare function prepareApplication(application: Application): Promise<void>;
+export type PrepareApplicationOptions = {
+    /**
+     * Runs against the built candidate while the live version is still serving, and BEFORE the swap. A
+     * throw here means the candidate never goes live — which is the whole difference from the previous
+     * behavior, where the swap committed first and a load failure was reported over an already-live
+     * broken release.
+     */
+    validateCandidate?: (candidateDirPath: string) => Promise<void>;
+};
+export declare function prepareApplication(application: Application, options?: PrepareApplicationOptions): Promise<void>;
 /**
  * Install all applications specified in the root config.
  *
@@ -228,9 +340,20 @@ export declare function materializeGitSSH(): Promise<{
 } | undefined>;
 export declare function buildNpmrcContent(registryCredentials: ResolvedRegistryCredential[]): string;
 /**
- * Run a command with the deploy's SSH key material materialized only for the duration of the
- * spawn. The keys are decrypted to a transient 0700 dir (see `materializeGitSSH`) and removed as
- * soon as the process settles — on success, failure, and timeout alike.
+ * Execute a command (using `spawn`) with stdin ignored, with the deploy's SSH key material
+ * materialized only for the duration of the spawn. The keys are decrypted to a transient 0700 dir
+ * (see `materializeGitSSH`) and removed as soon as the process settles — on success, failure, and
+ * timeout alike.
+ *
+ * Stdout is logged chunk-by-chunk. Stderr is buffered and then logged line-by-line.
+ *
+ * Rejects with an error if the command fails or times out.
+ *
+ * @param command The command to run.
+ * @param args The arguments to pass to the command.
+ * @param cwd The working directory for the command.
+ * @param timeoutMs The timeout for the command in milliseconds. Defaults to DEFAULT_COMMAND_TIMEOUT_MS.
+ * @returns A promise that resolves when the command completes.
  */
 export declare function nonInteractiveSpawn(applicationName: string, command: string, args: string[], cwd: string, timeoutMs?: number, onLine?: (stream: 'stdout' | 'stderr', line: string) => void, npmUserconfigPath?: string, gitCredentialEnv?: Record<string, string>): Promise<{
     stdout: string;