@harperfast/harper 5.2.0-beta.1 → 5.2.0-beta.2

package/bin/cliOperations.ts

@@ -9,6 +9,7 @@ import { httpRequest } from '../utility/common_utils.ts';
 import * as path from 'path';
 import * as fs from 'fs-extra';
 import * as YAML from 'yaml';
+import { Readable } from 'node:stream';
 import { streamPackagedDirectory, packageDirectory, scanPackageDirectory } from '../components/packageComponent.ts';
 import { encode as encodeCbor } from 'cbor-x';
 import { buildMultipartBody } from './multipartBuilder.ts';
@@ -19,6 +20,12 @@ import { initConfig, getConfigPath } from '../config/configUtils.ts';
 
 const OP_ALIASES = { deploy: 'deploy_component', package: 'package_component' };
 
+// Shown for any local-instance connection failure (missing pid, missing/stale domain
+// socket, or a refused/ENOENT connect against it) — they're all the same user-facing
+// scenario: Harper isn't running. Remote-target failures keep the detailed error instead,
+// since there's no single "just start it" fix for those.
+const LOCAL_NOT_RUNNING_MESSAGE = 'Harper is not running. Use `harperdb run` (or `harperdb start`) to start it.';
+
 // Operations whose responses should be consumed as text/event-stream so live phase events
 // (prepare, load, replicate, restart) render as they happen instead of after the whole
 // deploy completes. Add an operation here only after wiring its server-side
@@ -49,6 +56,34 @@ const TRANSPORT_ONLY_FIELDS = new Set([
 const STREAMING_DEPLOY_MIN_MAJOR = 5;
 const STREAMING_DEPLOY_MIN_MINOR = 1;
 
+// Idle-socket timeout for CLI Op-API requests: no traffic (in either direction) for this long
+// means the target is unreachable or wedged. Resets on any activity, so a slow-but-active
+// upload/deploy is unaffected — only a fully silent connection trips it. Overridable for
+// operations against known-slow targets.
+//
+// SSE-based operations (see SSE_OPERATIONS above) get a much longer default: a long-running
+// deploy_component can go quiet between phase events (e.g. a slow replicate/load step) for well
+// over a minute even though the connection is perfectly healthy, so the generic 60s default is
+// too tight for this one. HARPER_CLI_TIMEOUT_MS/CLI_TIMEOUT_MS, when set, overrides BOTH
+// defaults uniformly — it's a single "I know what timeout I want" escape hatch rather than two
+// separate env vars to keep in sync.
+const DEFAULT_CLI_OPERATION_TIMEOUT_MS = 60000;
+const DEFAULT_SSE_OPERATION_TIMEOUT_MS = 600000; // 10 minutes
+// Largest delay Node's setTimeout accepts; a larger value is silently coerced and fires in
+// ~1ms instead of the intended delay, so out-of-range input is treated the same as any other
+// invalid input below (falls back to DEFAULT_CLI_OPERATION_TIMEOUT_MS) rather than passed through.
+const MAX_CLI_OPERATION_TIMEOUT_MS = 2147483647; // 2^31 - 1
+const RAW_CLI_OPERATION_TIMEOUT = (process.env.HARPER_CLI_TIMEOUT_MS || process.env.CLI_TIMEOUT_MS)?.trim();
+const PARSED_CLI_OPERATION_TIMEOUT = RAW_CLI_OPERATION_TIMEOUT ? Number(RAW_CLI_OPERATION_TIMEOUT) : NaN;
+const CLI_OPERATION_TIMEOUT_OVERRIDE_MS =
+	Number.isInteger(PARSED_CLI_OPERATION_TIMEOUT) &&
+	PARSED_CLI_OPERATION_TIMEOUT >= 0 &&
+	PARSED_CLI_OPERATION_TIMEOUT <= MAX_CLI_OPERATION_TIMEOUT_MS
+		? PARSED_CLI_OPERATION_TIMEOUT
+		: undefined;
+const CLI_OPERATION_TIMEOUT_MS = CLI_OPERATION_TIMEOUT_OVERRIDE_MS ?? DEFAULT_CLI_OPERATION_TIMEOUT_MS;
+const SSE_OPERATION_TIMEOUT_MS = CLI_OPERATION_TIMEOUT_OVERRIDE_MS ?? DEFAULT_SSE_OPERATION_TIMEOUT_MS;
+
 /**
  * Parses a Harper version string (e.g. "5.0.31", "5.1.0-beta.2") and reports whether the
  * server is new enough to accept the multipart + SSE streaming deploy. Unparseable input
@@ -73,7 +108,11 @@ function versionSupportsStreamingDeploy(version: unknown): boolean {
  */
 async function targetSupportsStreamingDeploy(options: any): Promise<boolean> {
 	try {
-		const probeOptions = { ...options, headers: { ...options.headers, Accept: 'application/json' } };
+		const probeOptions = {
+			...options,
+			headers: { ...options.headers, Accept: 'application/json' },
+			timeout: CLI_OPERATION_TIMEOUT_MS,
+		};
 		delete probeOptions.streamResponse;
 		const response = await httpRequest(probeOptions, { operation: 'registration_info' });
 		if (response.statusCode !== 200 || !response.body) return true;
@@ -84,6 +123,21 @@ async function targetSupportsStreamingDeploy(options: any): Promise<boolean> {
 	}
 }
 
+// Wraps the local packaging stream so an fs error while tar'ing up the payload (e.g. a file
+// vanishing after the pre-deploy scan, or a permissions failure reading the project tree)
+// surfaces as a descriptive packaging error instead of a raw fs error code. Without this, an
+// ENOENT from *packaging* is indistinguishable from an ENOENT/ECONNREFUSED connecting to the
+// local domain socket, and the catch block below (which classifies purely on err.code) would
+// misreport it as "Harper is not running" even though Harper is running fine. Mirrors the
+// legacy deploy path's wrapping of packageDirectory() below.
+async function* wrapPackagingStream(stream: Readable, projectPath: string): AsyncGenerator<Buffer> {
+	try {
+		for await (const chunk of stream) yield chunk as Buffer;
+	} catch (err: any) {
+		throw new Error(`Failed to package component directory '${projectPath}': ${err.message}`, { cause: err });
+	}
+}
+
 // Build the JSON operation-field set from `req`, dropping the CLI's internal (`_`-prefixed)
 // and transport-only fields so neither the CLI internals nor credentials leak into the
 // request body. Shared by the multipart and legacy-JSON deploy body builders.
@@ -213,12 +267,12 @@ async function cliOperations(req: any, skipResponseLog = false) {
 		console.error('Connecting to local Harper instance');
 		initConfig();
 		if (!getHdbPid()) {
-			console.error('Harper must be running to perform this operation');
+			console.error(LOCAL_NOT_RUNNING_MESSAGE);
 			process.exit(1);
 		}
 
 		if (!fs.existsSync(getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET))) {
-			console.error('No domain socket found, unable to perform this operation');
+			console.error(LOCAL_NOT_RUNNING_MESSAGE);
 			process.exit(1);
 		}
 	}
@@ -230,6 +284,7 @@ async function cliOperations(req: any, skipResponseLog = false) {
 		};
 		options.method = 'POST';
 		options.headers = { 'Content-Type': 'application/json' };
+		options.timeout = SSE_OPERATIONS.has(req.operation) ? SSE_OPERATION_TIMEOUT_MS : CLI_OPERATION_TIMEOUT_MS;
 		if (target?.username) {
 			options.headers.Authorization = `Basic ${Buffer.from(`${target.username}:${target.password}`).toString('base64')}`;
 		} else if (allCredentials) {
@@ -244,7 +299,7 @@ async function cliOperations(req: any, skipResponseLog = false) {
 				if (tokens.refresh_token && isJWTExpired(tokens.operation_token)) {
 					console.error('Operation token expired, attempting to refresh...');
 					try {
-						const refreshOptions = { ...options };
+						const refreshOptions = { ...options, timeout: CLI_OPERATION_TIMEOUT_MS };
 						refreshOptions.headers = { ...options.headers, Authorization: `Bearer ${tokens.refresh_token}` };
 						const refreshResponse = await httpRequest(refreshOptions, {
 							operation: 'refresh_operation_token',
@@ -325,7 +380,7 @@ async function cliOperations(req: any, skipResponseLog = false) {
 				name: 'payload',
 				filename: 'package.tar.gz',
 				contentType: 'application/gzip',
-				stream: packageStream,
+				stream: Readable.from(wrapPackagingStream(packageStream, req._projectPath)),
 			});
 			options.headers['Content-Type'] = multipart.contentType;
 			// Use chunked transfer-encoding: we don't know the total size up front because the
@@ -432,14 +487,23 @@ async function cliOperations(req: any, skipResponseLog = false) {
 
 		return responseData;
 	} catch (err) {
-		if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
-			console.error(`error: Failed to connect to Harper (${err.code}): ${err.message}`);
-		} else if (err.code === 'EACCES') {
-			console.error(`error: Permission denied accessing the domain socket: ${err.message}`);
-		} else if (err.code === 'ENOTFOUND') {
-			console.error(`error: Host not found: "${err.hostname}" ${err.message}`);
+		let code, message, hostname;
+		try {
+			code = err?.code;
+			message = err?.message;
+			hostname = err?.hostname;
+		} catch {}
+		const isConnectionFailure = code === 'ENOENT' || code === 'ECONNREFUSED';
+		if (isConnectionFailure && !target) {
+			console.error(LOCAL_NOT_RUNNING_MESSAGE);
+		} else if (isConnectionFailure) {
+			console.error(`error: Failed to connect to Harper (${code}): ${message}`);
+		} else if (code === 'EACCES') {
+			console.error(`error: Permission denied accessing the domain socket: ${message}`);
+		} else if (code === 'ENOTFOUND') {
+			console.error(`error: Host not found: "${hostname}" ${message}`);
 		} else {
-			console.error(`error: ${err.message ?? err}`);
+			console.error(`error: ${message ?? err}`);
 		}
 		process.exit(1);
 	}

package/bin/run.ts

@@ -179,6 +179,16 @@ async function initialize(calledByInstall = false, calledByMain = false) {
 		process.exit(1);
 	}
 
+	// A built-in component only activates when its config key is present. Fresh installs get these
+	// keys from defaultConfig.yaml, but an in-place upgrade carries the old config forward without a
+	// key added in a newer release (harper-pro#585). Ensure them on every boot — idempotent and
+	// scoped to genuinely-new built-ins registered in this runtime — so the fix self-heals even when
+	// a version bump ships no upgrade directive or a prior backfill write failed.
+	const backfilledKeys = configUtils.ensureBuiltInComponentConfigKeys();
+	if (backfilledKeys.length > 0) {
+		hdbLogger.info(`Activated built-in component(s) absent from an upgraded config: ${backfilledKeys.join(', ')}`);
+	}
+
 	checkJwtTokens();
 
 	await keys.reviewSelfSignedCert();

package/bin/status.ts

@@ -61,5 +61,5 @@ async function status() {
 	}
 
 	console.log(YAML.stringify(status));
-	process.exit();
+	process.exit(0);
 }

package/components/Application.ts

@@ -186,8 +186,10 @@ export function isSSHAuthFailure(stderr: string): boolean {
 
 // Git-reference package identifier forms recognized below for the credentialed-clone path: the
 // npm git-url spec forms this repo's own derivePackageIdentifier can produce for a git host
-// credential. An identifier that doesn't match falls back to `npm pack --ignore-scripts` (best
-// effort, same as before this fix — not a regression for a form this can't safely reclone).
+// credential, plus the raw forms a caller may pass directly (any identifier containing ':' is
+// passed through as-is by derivePackageIdentifier). A form parseGitReference doesn't recognize but
+// looksLikeGitReference does is treated as "recognized as git, but not safely handleable" (see
+// extractApplication) rather than silently falling back to `npm pack --ignore-scripts`.
 const GIT_URL_PREFIX = /^git\+(ssh|https?|file):\/\//i;
 const GIT_PROTOCOL_PREFIX = /^git:\/\//i;
 
@@ -204,37 +206,89 @@ const HOSTED_GIT_HOSTS: Record<string, string> = {
 };
 const HOSTED_GIT_PREFIX = /^(github|gitlab|bitbucket|gist):(.+)$/i;
 
+// A bare `https://`/`http://` URL to one of the hosts above is *also* a git-reference install, not a
+// plain download: hosted-git-info (which npm's own git-arg resolution is built on) lists plain
+// http/https in every host's `protocols` array, so `npm pack https://github.com/owner/repo` clones
+// the repo exactly like the `git+https://` form does — it just doesn't carry the `git+` prefix that
+// would otherwise mark it as one.
+const BARE_GIT_HOST_URL_PREFIX = new RegExp(
+	`^https?://(${Object.values(HOSTED_GIT_HOSTS)
+		.map((host) => host.replace(/\./g, '\\.'))
+		.join('|')})/`,
+	'i'
+);
+
 interface GitReference {
 	cloneUrl: string;
 	committish?: string;
 }
 
+// True for a packageIdentifier that names a git source in some form parseGitReference recognizes OR
+// doesn't (a malformed hosted shorthand, or a `#path:` committish naming npm's monorepo-subdirectory
+// extension, which neither this nor the semver-committish resolution below implements). Lets
+// extractApplication distinguish "not git at all" (safe to fall back to plain `npm pack
+// --ignore-scripts`) from "git, but a form we can't safely reclone" (must fail loudly instead).
+function looksLikeGitReference(packageIdentifier: string): boolean {
+	return (
+		GIT_URL_PREFIX.test(packageIdentifier) ||
+		GIT_PROTOCOL_PREFIX.test(packageIdentifier) ||
+		HOSTED_GIT_PREFIX.test(packageIdentifier) ||
+		BARE_GIT_HOST_URL_PREFIX.test(packageIdentifier)
+	);
+}
+
 /**
- * Parses a `git+ssh://…`/`git+https://…`/`git+http://…`/`git+file://…`/`git://…`, or hosted-git
- * shorthand (`github:owner/repo`, `gitlab:owner/repo`, `bitbucket:owner/repo`, `gist:id`) package
- * identifier into a plain clone URL and optional committish, without depending on npm's own git-spec
- * parser (npm-package-arg/hosted-git-info aren't dependencies of this repo). Returns null for any
- * other form.
+ * Parses a `git+ssh://…`/`git+https://…`/`git+http://…`/`git+file://…`/`git://…`, a bare
+ * `https://`/`http://` URL to a known git host, or hosted-git shorthand (`github:owner/repo`,
+ * `gitlab:owner/repo`, `bitbucket:owner/repo`, `gist:[owner/]id`) package identifier into a plain
+ * clone URL and optional committish, without depending on npm's own git-spec parser
+ * (npm-package-arg/hosted-git-info aren't dependencies of this repo).
+ *
+ * Returns null for a `#path:` committish (npm's git-url monorepo-subdirectory extension, which this
+ * doesn't implement — a `#semver:` committish IS handled, downstream, by packGitReferenceWithoutScripts's
+ * resolveCommittish) or for a hosted shorthand that isn't a plain `owner/repo` (or `gist:[owner/]id`)
+ * — callers should treat that as "recognized as git, but not safely handleable" (see
+ * looksLikeGitReference) rather than silently falling back.
  */
 export function parseGitReference(packageIdentifier: string): GitReference | null {
 	const hashIndex = packageIdentifier.indexOf('#');
 	const committish = hashIndex === -1 ? undefined : packageIdentifier.slice(hashIndex + 1);
+	if (committish?.startsWith('path:')) return null;
 	const spec = hashIndex === -1 ? packageIdentifier : packageIdentifier.slice(0, hashIndex);
 	if (GIT_URL_PREFIX.test(spec)) return { cloneUrl: spec.slice('git+'.length), committish };
 	if (GIT_PROTOCOL_PREFIX.test(spec)) return { cloneUrl: spec, committish };
+	// Both of these forms are ones npm resolves via hosted-git-info, which — unlike the explicit
+	// `git+`/`git:` URL forms above — URL-decodes the whole committish while parsing it (e.g. a
+	// branch name containing `/` arriving as `%2F`-escaped resolves correctly either way, but a
+	// committish using other reserved characters needs this to match a real ref name).
+	const decodedCommittish = committish === undefined ? undefined : decodeURIComponentOrRaw(committish);
+	if (BARE_GIT_HOST_URL_PREFIX.test(spec)) return { cloneUrl: spec, committish: decodedCommittish };
 	const hostedMatch = HOSTED_GIT_PREFIX.exec(spec);
 	if (hostedMatch) {
 		const [, prefix, path] = hostedMatch;
 		const host = HOSTED_GIT_HOSTS[prefix.toLowerCase()];
-		// A gist clone URL is keyed by id alone; an optional `owner/` in the shorthand (npm accepts
-		// `gist:[owner/]id`) has no place in the URL and is dropped.
-		const urlPath =
-			prefix.toLowerCase() === 'gist' && path.includes('/') ? path.slice(path.lastIndexOf('/') + 1) : path;
-		return { cloneUrl: `https://${host}/${urlPath}.git`, committish };
+		if (prefix.toLowerCase() === 'gist') {
+			// A gist clone URL is keyed by id alone; an optional `owner/` in the shorthand (npm
+			// accepts `gist:[owner/]id`) has no place in the URL and is dropped.
+			const id = path.includes('/') ? path.slice(path.lastIndexOf('/') + 1) : path;
+			if (!/^[^/#:]+$/.test(id)) return null;
+			return { cloneUrl: `https://${host}/${id}.git`, committish: decodedCommittish };
+		}
+		if (!/^[^/#:]+\/[^/#:]+$/.test(path)) return null;
+		return { cloneUrl: `https://${host}/${path}.git`, committish: decodedCommittish };
 	}
 	return null;
 }
 
+/** decodeURIComponent, falling back to the raw input on a malformed escape rather than throwing. */
+function decodeURIComponentOrRaw(value: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+
 const NEUTRALIZED_LIFECYCLE_SCRIPTS = ['preinstall', 'install', 'postinstall', 'prepack', 'prepare'];
 
 // npm's hosted-git-info convention (documented in #1799's own worked example, `github:my-org/my-app#semver:v1.2.3`)
@@ -266,13 +320,8 @@ async function resolveCommittish(application: Application, committish: string, c
 	if (!SEMVER_COMMITTISH_PREFIX.test(committish)) return committish;
 	// npm's own package-arg parser URL-decodes the value after `semver:` (a range containing `^`/`~`
 	// can arrive percent-encoded, e.g. `#semver:%5E1.0.0`); do the same rather than evaluating it raw.
-	const rawRange = committish.slice('semver:'.length);
-	let range: string;
-	try {
-		range = decodeURIComponent(rawRange);
-	} catch {
-		range = rawRange;
-	}
+	// (A harmless no-op if parseGitReference already decoded the whole committish upstream.)
+	const range = decodeURIComponentOrRaw(committish.slice('semver:'.length));
 
 	// `git tag --list` rather than `for-each-ref --format=...`: nonInteractiveSpawn runs through a
 	// shell, and a `%(...)` format string is unsafe to pass through one.
@@ -371,33 +420,55 @@ async function packGitReferenceWithoutScripts(
 			await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
 		}
 
-		const { stdout, code, stderr } = await nonInteractiveSpawn(
-			application.name,
-			'npm',
-			['pack', '--json', '--ignore-scripts', cloneDir],
-			parentDirPath,
-			undefined,
-			undefined,
-			application.npmUserconfigPath
-		);
-		if (code !== 0) {
-			throw new Error(`Failed to pack package ${application.packageIdentifier}: ${stderr}`);
-		}
-		let packResult: Array<{ filename: string }>;
-		try {
-			packResult = JSON.parse(stdout.slice(stdout.indexOf('[')));
-		} catch (err) {
+		return await runNpmPack(application, ['pack', '--json', '--ignore-scripts', cloneDir], parentDirPath);
+	} finally {
+		await rm(cloneDir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Runs `npm pack` with the given args and returns the resulting tarball's path under `cwd`. Shared
+ * between the git-reference reclone path above and the plain identifier path in extractApplication.
+ */
+async function runNpmPack(
+	application: Application,
+	packArgs: string[],
+	cwd: string,
+	gitCredentialEnv?: Record<string, string>
+): Promise<string> {
+	const { stdout, code, stderr } = await nonInteractiveSpawn(
+		application.name,
+		'npm',
+		packArgs,
+		cwd,
+		undefined,
+		undefined,
+		application.npmUserconfigPath,
+		gitCredentialEnv
+	);
+	if (code !== 0) {
+		if (isSSHAuthFailure(stderr)) {
 			throw new Error(
-				`Failed to parse npm pack output for ${application.packageIdentifier}: ${err.message}\nstdout: ${stdout}`
+				`Failed to deploy private repository ${application.packageIdentifier}: SSH access failed. Verify the repository URL, configure an SSH key on this Harper instance, ensure the key has access to the target repository, and confirm the host is present in the ssh/known_hosts file.`,
+				{ cause: new Error(stderr) }
 			);
 		}
-		if (!Array.isArray(packResult) || typeof packResult[0]?.filename !== 'string') {
-			throw new Error(`Unexpected npm pack output for ${application.packageIdentifier}:\n${stdout}`);
-		}
-		return join(parentDirPath, packResult[0].filename);
-	} finally {
-		await rm(cloneDir, { recursive: true, force: true });
+		throw new Error(`Failed to download package ${application.packageIdentifier}: ${stderr}`);
+	}
+
+	let packResult: Array<{ filename: string }>;
+	try {
+		packResult = JSON.parse(stdout.slice(stdout.indexOf('[')));
+	} catch (err) {
+		throw new Error(
+			`Failed to parse npm pack output for ${application.packageIdentifier}: ${err.message}\nstdout: ${stdout}`
+		);
+	}
+	if (!Array.isArray(packResult) || typeof packResult[0]?.filename !== 'string') {
+		throw new Error(`Unexpected npm pack output for ${application.packageIdentifier}:\n${stdout}`);
 	}
+
+	return join(cwd, packResult[0].filename);
 }
 
 // Hidden directory under the components root holding component versions renamed aside
@@ -488,24 +559,37 @@ export async function extractApplication(application: Application) {
 			//
 			// Packing a git reference is not just a download: npm clones the repo and, if its manifest
 			// has a prepare/build/install script, runs `npm install` inside the clone and then that
-			// script — so the repo's own code AND its dependencies' install scripts execute on this node,
-			// inheriting this spawn's environment. With a credential session live, that is exactly the
-			// reach the credential must not have (a transitive dependency's postinstall could ask the
-			// socket for a token granted for the top-level repository), so scripts are off for a
-			// credentialed clone unless the deploy explicitly opted into them.
-			const scriptsDisallowed = application.gitCredentialEnv && !application.install?.allowInstallScripts;
+			// script — so the repository's (and its dependencies') install scripts can execute on this
+			// node during the pack step alone, independent of the later `npm install`.
+			// `install_allow_scripts` is the operator-facing switch for whether component code is
+			// allowed to run scripts on this node at all — with a credential session live, an
+			// unreviewed script also reaching the socket (a transitive dependency's postinstall asking
+			// for a token granted to the top-level repository) is exactly the reach the credential must
+			// not have, so this gates the pack step regardless of whether a credential happens to be in
+			// play.
+			const allowScripts = !!application.install?.allowInstallScripts;
 			// `--ignore-scripts` alone isn't a reliable way to enforce that: pacote's DirFetcher runs a
 			// git source's `prepare` unconditionally on npm versions before 11.0.0 (see
 			// packGitReferenceWithoutScripts), which is exactly what Node 22's bundled npm ships. For a
 			// recognized git-reference identifier, clone and pack it ourselves with scripts stripped
 			// instead, sidestepping that npm code path entirely.
-			const gitRef = scriptsDisallowed ? parseGitReference(application.packageIdentifier) : null;
+			const gitRef = allowScripts ? null : parseGitReference(application.packageIdentifier);
+
+			if (!allowScripts && !gitRef && looksLikeGitReference(application.packageIdentifier)) {
+				// Recognized as git, but a form the reclone-and-strip-scripts path above can't safely
+				// handle (a `#path:` committish, or a hosted shorthand other than a plain `owner/repo`) —
+				// fail loudly rather than silently falling through to the unreliable `npm pack
+				// --ignore-scripts` below.
+				throw new Error(
+					`Cannot deploy git-reference package '${application.packageIdentifier}' with install scripts disallowed: this identifier's form (e.g. a '#path:' committish, or a hosted shorthand other than a plain 'owner/repo') isn't one this repo's script-suppression handling supports. Set install.allowInstallScripts to true, or use a plain git URL with a branch/tag/commit committish instead.`
+				);
+			}
 
 			if (gitRef) {
 				tarballPath = await packGitReferenceWithoutScripts(application, gitRef, parentDirPath);
 			} else {
 				const packArgs = ['pack', '--json', application.packageIdentifier];
-				if (scriptsDisallowed) {
+				if (!allowScripts) {
 					packArgs.push('--ignore-scripts');
 				} else if (application.gitCredentialEnv) {
 					application.logger.warn(
@@ -514,39 +598,7 @@ export async function extractApplication(application: Application) {
 							`can read the git credential. Unset install_allow_scripts to keep the credential out of their reach.`
 					);
 				}
-				const { stdout, code, stderr } = await nonInteractiveSpawn(
-					application.name,
-					'npm',
-					packArgs,
-					parentDirPath,
-					undefined,
-					undefined,
-					application.npmUserconfigPath,
-					application.gitCredentialEnv
-				);
-				if (code !== 0) {
-					if (isSSHAuthFailure(stderr)) {
-						throw new Error(
-							`Failed to deploy private repository ${application.packageIdentifier}: SSH access failed. Verify the repository URL, configure an SSH key on this Harper instance, ensure the key has access to the target repository, and confirm the host is present in the ssh/known_hosts file.`,
-							{ cause: new Error(stderr) }
-						);
-					}
-					throw new Error(`Failed to download package ${application.packageIdentifier}: ${stderr}`);
-				}
-
-				let packResult: Array<{ filename: string }>;
-				try {
-					packResult = JSON.parse(stdout.slice(stdout.indexOf('[')));
-				} catch (err) {
-					throw new Error(
-						`Failed to parse npm pack output for ${application.packageIdentifier}: ${err.message}\nstdout: ${stdout}`
-					);
-				}
-				if (!Array.isArray(packResult) || typeof packResult[0]?.filename !== 'string') {
-					throw new Error(`Unexpected npm pack output for ${application.packageIdentifier}:\n${stdout}`);
-				}
-
-				tarballPath = join(parentDirPath, packResult[0].filename);
+				tarballPath = await runNpmPack(application, packArgs, parentDirPath, application.gitCredentialEnv);
 			}
 			shouldDeleteTarball = true;
 			tarball = createReadStream(tarballPath);
@@ -582,6 +634,9 @@ export async function extractApplication(application: Application) {
 			throw err;
 		}
 	}
+	// A directory existed for this component name prior to this deploy, so this is a redeploy of
+	// an already-active component rather than a first-time deploy. See `isNewComponent` above.
+	if (didRenameAside) application.isNewComponent = false;
 	// Finally, create the application directory fresh
 	await mkdir(application.dirPath, { recursive: true });
 
@@ -848,6 +903,14 @@ export class Application {
 	npmUserconfigPath?: string;
 	#npmrcTempDir?: string;
 	#gitCredentialSession?: GitCredentialSession;
+	// Whether this component's directory did not already exist when extractApplication ran —
+	// i.e. this deploy is the component's first, as opposed to a redeploy of something already
+	// active. Defaults true and is flipped to false by extractApplication when it finds (and
+	// renames aside) a pre-existing directory for this component name. Used by deployComponent to
+	// scope its unconditional requestRestart() call to genuinely new components (harper#1806):
+	// an existing, already-loaded component already has a live file watcher (Scope/EntryHandler)
+	// that independently requests a restart if the redeploy actually needs one.
+	isNewComponent: boolean = true;
 
 	constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }: ApplicationOptions) {
 		this.name = name;

package/components/Scope.ts

@@ -76,6 +76,10 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 	ready: Promise<any[]>;
 	databaseEvents: typeof databaseEventsEmitter;
 	models: Models;
+	// Set by the loader on deploy pre-flight validation loads (collectScopes):
+	// the scope exists to validate a component, not to run it. Plugins with
+	// process-global side effects should validate fully but skip activation.
+	isTransientValidation?: boolean;
 
 	constructor(
 		appName: string,

package/components/componentLoader.ts

@@ -25,6 +25,7 @@ import * as staticFiles from '../server/static.ts';
 import * as loadEnv from '../resources/loadEnv.ts';
 import harperLogger, { errorForLog } from '../utility/logging/harper_logger.ts';
 import * as dataLoader from '../resources/dataLoader.ts';
+import * as scheduler from '../resources/scheduler/scheduler.ts';
 import { restartWorkers, getWorkerIndex } from '../server/threads/manageThreads.js';
 import { resetRestartNeeded, subscribeToRestartRequests } from './requestRestart.ts';
 import { trackScopeClose } from './scopeShutdown.ts';
@@ -121,6 +122,7 @@ export const TRUSTED_RESOURCE_PLUGINS: any = {
 	logging: harperLogger,
 	dataLoader,
 	mcp: mcpComponent,
+	scheduler,
 	/*
 	static: ...
 	login: ...
@@ -560,6 +562,11 @@ export async function loadComponent(
 						// load is validated (see operations.js deploy pre-flight). Skip the worker-shutdown
 						// auto-close so their deploy-lifecycle listeners — and this SHUTDOWN handler — don't
 						// accumulate across deploys (#1462).
+						// Mark it so plugins with process-global side effects (e.g. the scheduler
+						// registering jobs into its engine) can validate without activating —
+						// validation scopes may reuse a live component's identity, so activating
+						// from one can displace the real component's registrations.
+						scope.isTransientValidation = true;
 						options.collectScopes.add(scope);
 					} else {
 						// Track the close so the worker's shutdown path waits for it (and thus for any async

package/components/operations.js

@@ -611,7 +611,27 @@ async function deployComponent(req) {
 
 			response.restartJobId = jobResponse.job_id;
 			response.message = `Successfully deployed: ${application.name}, restarting Harper`;
-		} else response.message = `Successfully deployed: ${application.name}`;
+		} else {
+			// Deployed without restarting: for a component that had no directory before this
+			// deploy — genuinely new, never loaded — its routes cannot be live until Harper
+			// restarts, so mark a restart as needed. This is the setter only; it does not itself
+			// restart. It makes get_status report restartRequired:true and lets the REST
+			// route-miss path surface the actionable "needs a restart" 404 for a freshly deployed,
+			// never-loaded component (harper#674). Runs per-node: a peer applying the replicated
+			// deploy checks its own local isNewComponent, since directory state (and therefore
+			// whether the component was already active) can differ per node.
+			//
+			// An existing, already-active component being redeployed does NOT force a restart
+			// here: some updates (e.g. static files only) may not need one at all, and when one
+			// genuinely is needed, that component's already-running file watcher (Scope/
+			// EntryHandler, see deployLifecycle.ts) independently detects the post-deploy file
+			// changes and requests the restart itself.
+			if (application.isNewComponent) {
+				const { requestRestart } = require('./requestRestart.ts');
+				requestRestart();
+			}
+			response.message = `Successfully deployed: ${application.name}`;
+		}
 
 		// Replication failures don't reject replicateOperation — they surface as 'failed'
 		// entries in peer_results. By default, treat any failed peer as an overall deploy