@kici-dev/agent 0.1.9 → 0.1.11

package/dist/index.js

@@ -2,11 +2,18 @@ import { fileURLToPath as __cjs_fileURLToPath } from "node:url";
 import { dirname as __cjs_dirname } from "node:path";
 __cjs_dirname(__cjs_fileURLToPath(import.meta.url));
 import "node:module";
-import { hostname } from "node:os";
+import { hostname, tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
 import { KNOWN_ROLES, validateNoReservedLabels } from "@kici-dev/engine";
+import { execFile } from "node:child_process";
+import { access, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { createLogger, toErrorMessage } from "@kici-dev/shared";
+import { PackageManager, detectPackageManagerFromManifests } from "@kici-dev/shared/package-manager";
+import { existsSync } from "node:fs";
 import.meta.url;
 //#endregion
 //#region src/config.ts
@@ -123,6 +130,519 @@ function loadConfig() {
 	};
 }
 //#endregion
-export { loadConfig };
+//#region src/execution/npm-resolver.ts
+/**
+* Resolve the npm CLI path relative to the running Node.js binary.
+*
+* Used both at startup (builder role readiness check) and at install time
+* (dep-installer). Centralizes the resolution logic so it stays consistent.
+*
+* Resolution strategy:
+* 1. Check standard Node.js layout paths relative to process.execPath
+* 2. Fall back to bare 'npm' on PATH (development environments)
+*/
+/**
+* Resolve the npm CLI path from the current Node.js binary.
+*
+* Checks standard Node.js distribution layout paths:
+* - {nodeDir}/../lib/node_modules/npm/bin/npm-cli.js (Linux/macOS installed)
+* - {nodeDir}/node_modules/npm/bin/npm-cli.js (Windows / some layouts)
+*
+* Returns undefined npmCliPath if neither is found (caller can fall back to PATH).
+*/
+function resolveNpm() {
+	const nodeExe = process.execPath;
+	const nodeDir = dirname(nodeExe);
+	return {
+		npmCliPath: [join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"), join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js")].find((p) => existsSync(p)),
+		nodeExe,
+		nodeDir
+	};
+}
+//#endregion
+//#region src/execution/npm-registry-config.ts
+/**
+* Apply private-npm-registry auth to a workflow's `.kici/.npmrc` for the
+* lifetime of one `npm install` invocation, then restore the file on cleanup.
+*
+* Why a closure-cleanup pattern (mirrors `setupSshAuth.cleanup()` in
+* `packages/agent/src/checkout/git-clone.ts`): the customer's committed
+* `.kici/.npmrc` may carry literal `${VAR}` placeholders or an unrelated
+* scope mapping. We must NOT clobber it permanently — we just want to
+* append the agent-managed registry/auth lines for this single install,
+* then revert.
+*
+* Token bytes never end up in the on-disk `.npmrc`. Each registry's token
+* is exposed as a job-scoped env var (`KICI_NPM_TOKEN_${jobIdShort}_<i>`)
+* and the on-disk auth line carries the env var reference (`${VAR}`). npm
+* substitutes at read time. The job-scoped nonce makes the env var name
+* unguessable from outside the install subprocess.
+*
+* Merge order: customer-committed `.npmrc` lines come FIRST, agent-generated
+* lines come LAST. npm's last-wins semantics make the agent's line shadow
+* any literal `_authToken=...` the customer accidentally committed for a
+* registry KiCI manages — refuses to let a committed secret beat a managed
+* one.
+*
+* `installEnvSecrets` is a separate channel for customers who prefer the
+* "commit a `.kici/.npmrc` with `${MY_TOKEN}` and supply MY_TOKEN as a
+* scoped secret" pattern (Option C in the design doc). Each entry becomes
+* an env var on the install subprocess; the customer's existing `.npmrc`
+* uses it as `${MY_TOKEN}`.
+*/
+/** No-op result returned when nothing needs to be applied. */
+function noopResult() {
+	return {
+		extraEnv: {},
+		tokensForRedaction: [],
+		cleanup: async () => {}
+	};
+}
+/** Build the synthesized env-var name for registry index `i`. */
+function tokenEnvName(jobIdShort, index) {
+	return `KICI_NPM_TOKEN_${jobIdShort}_${index}`;
+}
+/** Render the agent-managed block of `.npmrc` lines. */
+function renderAgentLines(registries, jobIdShort) {
+	if (registries.length === 0) return "";
+	const lines = [];
+	for (let i = 0; i < registries.length; i++) {
+		const reg = registries[i];
+		const envVar = tokenEnvName(jobIdShort, i);
+		const authKey = reg.url.replace(/^https?:/, "");
+		if (reg.scope) lines.push(`${reg.scope}:registry=${reg.url}`);
+		else lines.push(`registry=${reg.url}`);
+		lines.push(`${authKey}:_authToken=\${${envVar}}`);
+		if (reg.alwaysAuth) lines.push(`${authKey}:always-auth=true`);
+	}
+	return `# kici-managed: applied for one npm install only\n${lines.join("\n")}\n`;
+}
+/** Read original `.npmrc` bytes; null if the file does not exist. */
+async function readOriginalNpmrc(npmrcPath) {
+	try {
+		return await readFile(npmrcPath, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* Apply the merged `.npmrc` and return env + redaction + cleanup. Caller
+* runs the npm install with `extraEnv` merged in, then awaits cleanup()
+* inside the install's `finally`.
+*/
+async function applyNpmRegistryConfig(args) {
+	const registries = args.npmRegistries ?? [];
+	const installEnvSecrets = args.installEnvSecrets ?? {};
+	if (registries.length === 0 && Object.keys(installEnvSecrets).length === 0) return noopResult();
+	const npmrcPath = join(args.kiciDir, ".npmrc");
+	const original = await readOriginalNpmrc(npmrcPath);
+	const tokenEnv = {};
+	const tokensForRedaction = [];
+	for (let i = 0; i < registries.length; i++) {
+		tokenEnv[tokenEnvName(args.jobIdShort, i)] = registries[i].token;
+		tokensForRedaction.push(registries[i].token);
+	}
+	for (const value of Object.values(installEnvSecrets)) if (value) tokensForRedaction.push(value);
+	const agentBlock = renderAgentLines(registries, args.jobIdShort);
+	const merged = `${original ?? ""}${original && !original.endsWith("\n") ? "\n" : ""}${agentBlock}`;
+	if (agentBlock.length > 0) await writeFile(npmrcPath, merged, {
+		encoding: "utf8",
+		mode: 384
+	});
+	const cleanup = async () => {
+		if (agentBlock.length === 0) return;
+		try {
+			if (original === null) await unlink(npmrcPath).catch(() => {});
+			else await writeFile(npmrcPath, original, { encoding: "utf8" });
+		} catch {}
+	};
+	return {
+		extraEnv: {
+			...installEnvSecrets,
+			...tokenEnv
+		},
+		tokensForRedaction,
+		cleanup
+	};
+}
+/** Mask every token in `tokensForRedaction` out of `input` before logging. */
+function redactNpmOutput(input, tokens) {
+	if (!input) return input;
+	let out = input;
+	for (const token of tokens) {
+		if (!token) continue;
+		out = out.split(token).join("***REDACTED***");
+	}
+	return out;
+}
+//#endregion
+//#region src/execution/validate-kici-deps.ts
+/**
+* Pre-install validation for `.kici/` dependency specifiers.
+*
+* The agent clones a single source repository and installs its `.kici/`
+* dependencies with the repo's package manager. Local-protocol specifiers —
+* `workspace:`, `file:`, `link:`, `portal:` — resolve a dependency against
+* another package on the same filesystem rather than a registry. Whether they
+* are resolvable depends on the manager and the layout:
+*
+* - npm has no `workspace:` protocol and cannot resolve any of these from a
+*   registry, so they are rejected up front with an actionable message
+*   instead of the raw `EUNSUPPORTEDPROTOCOL` npm would emit.
+* - pnpm resolves `workspace:` against the repo's pnpm workspace (the agent
+*   clones the whole repo, so an in-repo sibling is present), and resolves
+*   `file:`/`link:`/`portal:` against a path — allowed when that path stays
+*   inside the cloned repo, rejected when it escapes the clone.
+*
+* This module performs that classification so unresolvable specifiers fail
+* fast with guidance rather than a cryptic install error.
+*/
+/** Local-protocol specifier prefixes that resolve against the filesystem. */
+let LocalDepProtocol = /* @__PURE__ */ function(LocalDepProtocol) {
+	LocalDepProtocol["Workspace"] = "workspace:";
+	LocalDepProtocol["File"] = "file:";
+	LocalDepProtocol["Link"] = "link:";
+	LocalDepProtocol["Portal"] = "portal:";
+	return LocalDepProtocol;
+}({});
+const LOCAL_PROTOCOLS = [
+	"workspace:",
+	"file:",
+	"link:",
+	"portal:"
+];
+/** The dependency maps a package manager resolves in `.kici/package.json`. */
+const DEP_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+/**
+* Scan a parsed `.kici/package.json` for dependency specifiers that use a
+* local protocol (`workspace:`/`file:`/`link:`/`portal:`). Returns one entry
+* per dependency, in field order. Returns an empty array when there are none.
+*/
+function findLocalProtocolDeps(pkg) {
+	const found = [];
+	for (const field of DEP_FIELDS) {
+		const deps = pkg[field];
+		if (!deps || typeof deps !== "object") continue;
+		for (const [name, spec] of Object.entries(deps)) {
+			if (typeof spec !== "string") continue;
+			const protocol = LOCAL_PROTOCOLS.find((proto) => spec.startsWith(proto));
+			if (protocol) found.push({
+				name,
+				spec,
+				protocol
+			});
+		}
+	}
+	return found;
+}
+/** Parse `.kici/package.json`, returning `null` when it is missing or invalid. */
+async function readKiciPackageJson(kiciDir) {
+	let raw;
+	try {
+		raw = await readFile(join(kiciDir, "package.json"), "utf-8");
+	} catch {
+		return null;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether `.kici/package.json` declares any local-protocol dependency. Used to
+* decide whether the agent must build the in-repo workspace dependency closure
+* after a pnpm install (so a `workspace:` sibling's build output exists before
+* the workflow that imports it loads).
+*/
+async function kiciHasLocalProtocolDeps(kiciDir) {
+	const pkg = await readKiciPackageJson(kiciDir);
+	if (!pkg) return false;
+	return findLocalProtocolDeps(pkg).length > 0;
+}
+async function fileExists(target) {
+	try {
+		await access(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Resolve a `file:`/`link:`/`portal:` spec to an absolute path under kiciDir. */
+function resolveLocalPath(kiciDir, dep) {
+	const rawPath = dep.spec.slice(dep.protocol.length);
+	return isAbsolute(rawPath) ? resolve(rawPath) : resolve(kiciDir, rawPath);
+}
+/** Whether `target` is `repoRoot` itself or a path inside it. */
+function isInsideRepo(repoRoot, target) {
+	const rel = relative(repoRoot, target);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+* Classify each local-protocol dependency for the detected package manager and
+* return the ones that are unresolvable in the agent's single-clone model.
+*/
+async function findUnresolvableDeps(deps, packageManager, kiciDir, repoRoot) {
+	if (packageManager === PackageManager.Npm) return [...deps];
+	const hasWorkspaceFile = await fileExists(join(repoRoot, "pnpm-workspace.yaml"));
+	const unresolvable = [];
+	for (const dep of deps) {
+		if (dep.protocol === "workspace:") {
+			if (!hasWorkspaceFile) unresolvable.push(dep);
+			continue;
+		}
+		if (!isInsideRepo(repoRoot, resolveLocalPath(kiciDir, dep))) unresolvable.push(dep);
+	}
+	return unresolvable;
+}
+/** Build the actionable error for unresolvable local-protocol dependencies. */
+function formatUnresolvableDepError(offenders, packageManager) {
+	const list = offenders.map((o) => `${o.name}: ${o.spec}`).join(", ");
+	if (packageManager === PackageManager.Npm) return `These .kici/ dependencies use local-protocol specifiers npm cannot resolve from a registry: ${list}. npm has no workspace protocol — pin a published version, publish the package to your registry, or use pnpm so an in-repo workspace sibling can be resolved.`;
+	return `These .kici/ dependencies point outside the cloned repository, which the agent never has: ${list}. A workspace: dependency requires a pnpm-workspace.yaml at the repo root, and file:/link:/portal: paths must stay inside this repository.`;
+}
+/**
+* Throw an actionable error when `.kici/package.json` declares a local-protocol
+* dependency the detected package manager cannot resolve from the single cloned
+* repository. A missing or unparseable package.json is left for the install to
+* report.
+*/
+async function assertResolvableDeps(args) {
+	const pkg = await readKiciPackageJson(args.kiciDir);
+	if (!pkg) return;
+	const localDeps = findLocalProtocolDeps(pkg);
+	if (localDeps.length === 0) return;
+	const offenders = await findUnresolvableDeps(localDeps, args.packageManager, args.kiciDir, args.repoRoot);
+	if (offenders.length === 0) return;
+	throw new Error(formatUnresolvableDepError(offenders, args.packageManager));
+}
+//#endregion
+//#region src/execution/dep-installer.ts
+/**
+* Inline dependency installation for graceful degradation.
+*
+* When the dep cache is unavailable or a download fails, the agent installs
+* `.kici/` dependencies directly with the repository's package manager.
+*
+* The package manager is detected from the cloned repo (npm / pnpm); the
+* presence of `.kici/package.json` signals that deps should be installed. npm
+* is the default and ships with every Node.js install; pnpm is used when the
+* repo is a pnpm workspace so a `.kici/` member can resolve in-repo
+* `workspace:` siblings. yarn is detected but not yet supported and is
+* rejected with an actionable error.
+*
+* Security: the install runs with an isolated per-invocation cache/store
+* directory to prevent cache poisoning across build jobs — a malicious
+* package.json in one repo cannot taint the cache used by subsequent builds.
+* The same pressure rules out letting lifecycle scripts see synthesized auth
+* env vars — the install runs with `--ignore-scripts` whenever a private
+* registry is configured.
+*/
+const logger = createLogger({ prefix: "dep-installer" });
+const execFileAsync = promisify(execFile);
+/** Install subprocess timeout (10 min) and stdout/stderr buffer (128 MiB). */
+const INSTALL_TIMEOUT_MS = 6e5;
+const INSTALL_MAX_BUFFER = 128 * 1024 * 1024;
+/**
+* Detect the package manager for the cloned repo from its committed manifests.
+* A pnpm workspace's `packageManager` field + `pnpm-lock.yaml` live at the repo
+* root, so check there first; fall back to `.kici/` for a standalone
+* (non-workspace) project that carries its own lockfile; default to npm when
+* neither carries a signal. Uses the manifests-only detector so the agent's own
+* launch env (`npm_config_user_agent`) never leaks into the decision.
+*/
+async function detectKiciPackageManager(repoRoot, kiciDir) {
+	return await detectPackageManagerFromManifests(repoRoot) ?? await detectPackageManagerFromManifests(kiciDir) ?? PackageManager.Npm;
+}
+/**
+* Install `.kici/` dependencies inline with the repo's package manager.
+*
+* Falls back to this when the dep cache is unavailable or a download fails.
+* The install runs with an isolated cache/store directory (created in
+* `os.tmpdir()`) to prevent cache poisoning between build jobs; the directory
+* is removed after installation.
+*
+* If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, a job-scoped
+* `.kici/.npmrc` overlay is synthesized for the install, restored in `finally`,
+* and the install runs with `--ignore-scripts` so lifecycle scripts in a
+* committed `package.json` cannot exfiltrate the synthesized token env vars.
+*
+* @param kiciDir - Path to the `.kici/` directory containing package.json.
+* @param opts    - Optional registry / installEnv / repoRoot configuration.
+*/
+async function installDeps(kiciDir, opts = {}) {
+	const repoRoot = opts.repoRoot ?? dirname(kiciDir);
+	const packageManager = await detectKiciPackageManager(repoRoot, kiciDir);
+	logger.info("Installing deps inline", {
+		packageManager,
+		dir: kiciDir
+	});
+	process.stderr.write(`[dep-installer:trace] starting install: pm=${packageManager}, cwd=${kiciDir}\n`);
+	if (packageManager === PackageManager.Yarn) throw new Error("This repository uses yarn, which the KiCI agent does not yet support for .kici/ dependency installation. Use npm or pnpm for the .kici/ project, or open a feature request for yarn support.");
+	await assertResolvableDeps({
+		kiciDir,
+		repoRoot,
+		packageManager
+	});
+	const startTime = Date.now();
+	const hasPrivateRegistry = (opts.npmRegistries?.length ?? 0) > 0 || (opts.installEnvSecrets ? Object.keys(opts.installEnvSecrets).length > 0 : false);
+	const registryConfig = await applyNpmRegistryConfig({
+		kiciDir,
+		npmRegistries: opts.npmRegistries,
+		installEnvSecrets: opts.installEnvSecrets,
+		jobIdShort: opts.jobIdShort ?? "00000000"
+	});
+	try {
+		if (packageManager === PackageManager.Pnpm) await runPnpmInstall({
+			kiciDir,
+			hasPrivateRegistry,
+			registryConfig
+		});
+		else await runNpmInstall({
+			kiciDir,
+			hasPrivateRegistry,
+			registryConfig
+		});
+	} catch (e) {
+		const tokens = registryConfig.tokensForRedaction;
+		process.stderr.write(`[dep-installer:trace] INSTALL FAILED: ${redactNpmOutput(toErrorMessage(e), tokens)}\n`);
+		logSubprocessStreams(e, tokens);
+		throw e;
+	} finally {
+		await registryConfig.cleanup();
+	}
+	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot);
+	const durationMs = Date.now() - startTime;
+	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
+	logger.info("Deps installed inline", {
+		packageManager,
+		durationMs
+	});
+}
+/** Build the Node binary directory onto PATH so spawned tools find `node`. */
+function envWithNodeOnPath(extraEnv, nodeDir) {
+	const { NODE_ENV: _NODE_ENV, ...restEnv } = process.env;
+	return {
+		...restEnv,
+		...extraEnv,
+		PATH: `${nodeDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
+	};
+}
+/** Run `npm install` in `.kici/` with an isolated cache directory. */
+async function runNpmInstall(args) {
+	const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
+	const cacheDir = await mkdtemp(join(tmpdir(), "kici-npm-cache-"));
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const buildArgs = (...prefix) => {
+		const a = [
+			...prefix,
+			"install",
+			"--cache",
+			cacheDir,
+			"--no-audit",
+			"--no-fund"
+		];
+		if (args.hasPrivateRegistry) a.push("--ignore-scripts");
+		return a;
+	};
+	try {
+		const bin = npmCliPath ? nodeExe : "npm";
+		const argv = npmCliPath ? buildArgs(npmCliPath) : buildArgs();
+		process.stderr.write(`[dep-installer:trace] running: ${bin} ${argv.join(" ")}\n`);
+		await execFileAsync(bin, argv, {
+			cwd: args.kiciDir,
+			env,
+			timeout: INSTALL_TIMEOUT_MS,
+			maxBuffer: INSTALL_MAX_BUFFER
+		});
+	} finally {
+		await rm(cacheDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
+* Run `pnpm install` from `.kici/`. pnpm walks up to the workspace root, so a
+* `workspace:` sibling in the same cloned repo resolves. Uses an isolated store
+* (`--config.store-dir`) for cross-job isolation, `package-import-method=copy`
+* so the on-disk store is a self-contained tree of real files (a later dep
+* cache tars it), and disables interactive purge prompts + the side-effects
+* cache for deterministic, non-interactive runs.
+*/
+async function runPnpmInstall(args) {
+	await assertPnpmAvailable();
+	const { nodeDir } = resolveNpm();
+	const storeDir = await mkdtemp(join(tmpdir(), "kici-pnpm-store-"));
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const argv = [
+		"install",
+		`--config.store-dir=${storeDir}`,
+		"--config.package-import-method=copy",
+		"--config.confirm-modules-purge=false",
+		"--config.side-effects-cache=false"
+	];
+	if (args.hasPrivateRegistry) argv.push("--ignore-scripts");
+	try {
+		process.stderr.write(`[dep-installer:trace] running: pnpm ${argv.join(" ")}\n`);
+		await execFileAsync("pnpm", argv, {
+			cwd: args.kiciDir,
+			env,
+			timeout: INSTALL_TIMEOUT_MS,
+			maxBuffer: INSTALL_MAX_BUFFER
+		});
+	} finally {
+		await rm(storeDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
+* Build the in-repo dependency closure of the `.kici/` package so a
+* `workspace:` sibling's build output exists before the workflow that imports
+* it loads. `--filter "{.kici}^..."` selects only `.kici`'s dependencies (not
+* `.kici` itself); `--if-present` skips siblings without a build script. Runs
+* with a clean env (no synthesized registry tokens).
+*/
+async function buildWorkspaceClosure(repoRoot) {
+	const { nodeDir } = resolveNpm();
+	const env = envWithNodeOnPath({}, nodeDir);
+	const argv = [
+		"--filter",
+		"{.kici}^...",
+		"run",
+		"build",
+		"--if-present"
+	];
+	process.stderr.write(`[dep-installer:trace] building workspace closure: pnpm ${argv.join(" ")}\n`);
+	await execFileAsync("pnpm", argv, {
+		cwd: repoRoot,
+		env,
+		timeout: INSTALL_TIMEOUT_MS,
+		maxBuffer: INSTALL_MAX_BUFFER
+	});
+}
+/** Throw an actionable error when the repo needs pnpm but it is not installed. */
+async function assertPnpmAvailable() {
+	try {
+		await execFileAsync("pnpm", ["--version"], { timeout: 3e4 });
+	} catch (e) {
+		throw new Error(`This repository is a pnpm workspace, but pnpm is not available on this agent. Install pnpm (e.g. \`corepack enable\`) or run on a container/ Firecracker agent that bundles it. (${toErrorMessage(e)})`);
+	}
+}
+/** Trace the redacted stdout/stderr of a failed install subprocess. */
+function logSubprocessStreams(e, tokens) {
+	if (e && typeof e === "object" && "stdout" in e) process.stderr.write(`[dep-installer:trace] stdout: ${redactNpmOutput(String(e.stdout), tokens).slice(0, 500)}\n`);
+	if (e && typeof e === "object" && "stderr" in e) process.stderr.write(`[dep-installer:trace] stderr: ${redactNpmOutput(String(e.stderr), tokens).slice(0, 500)}\n`);
+}
+//#endregion
+export { LocalDepProtocol, assertResolvableDeps, findLocalProtocolDeps, formatUnresolvableDepError, installDeps, kiciHasLocalProtocolDeps, loadConfig };
 
 //# sourceMappingURL=index.js.map