@kici-dev/agent 0.1.16 → 0.1.17

package/dist/index.js

@@ -5,7 +5,7 @@ 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, cp, mkdir, mkdtemp, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { createLogger, sha256, toErrorMessage } from "@kici-dev/shared";
@@ -309,6 +309,11 @@ function redactNpmOutput(input, tokens) {
 *   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.
+* - yarn classic (v1) has no `workspace:` protocol and no `portal:` — it links
+*   in-repo siblings by version range, not by a local specifier — so both are
+*   rejected with guidance; `file:`/`link:` are allowed when the path stays
+*   inside the clone, rejected when it escapes. (yarn berry is not yet
+*   supported.)
 *
 * This module performs that classification so unresolvable specifiers fail
 * fast with guidance rather than a cryptic install error.
@@ -405,6 +410,17 @@ function isInsideRepo(repoRoot, target) {
 */
 async function findUnresolvableDeps(deps, packageManager, kiciDir, repoRoot) {
 	if (packageManager === PackageManager.Npm) return [...deps];
+	if (packageManager === PackageManager.Yarn) {
+		const unresolvable = [];
+		for (const dep of deps) {
+			if (dep.protocol === "workspace:" || dep.protocol === "portal:") {
+				unresolvable.push(dep);
+				continue;
+			}
+			if (!isInsideRepo(repoRoot, resolveLocalPath(kiciDir, dep))) unresolvable.push(dep);
+		}
+		return unresolvable;
+	}
 	const hasWorkspaceFile = await fileExists(join(repoRoot, "pnpm-workspace.yaml"));
 	const unresolvable = [];
 	for (const dep of deps) {
@@ -420,6 +436,7 @@ async function findUnresolvableDeps(deps, packageManager, kiciDir, repoRoot) {
 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.`;
+	if (packageManager === PackageManager.Yarn) return `These .kici/ dependencies use specifiers yarn classic cannot resolve: ${list}. yarn classic has no workspace: or portal: protocol — reference an in-repo sibling by a version range (yarn links matching workspace members), use pnpm, or keep file:/link: paths inside this repository. (yarn berry support is planned.)`;
 	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.`;
 }
 /**
@@ -438,6 +455,101 @@ async function assertResolvableDeps(args) {
 	throw new Error(formatUnresolvableDepError(offenders, args.packageManager));
 }
 //#endregion
+//#region src/execution/workspace-siblings.ts
+/**
+* In-repo workspace-sibling discovery for the agent's dependency handling.
+*
+* A pnpm or yarn-classic workspace lays out a `.kici/` member's `workspace:`
+* (pnpm) or version-range (yarn) siblings as symlinks pointing at package
+* directories that live inside the clone but outside `.kici/` and outside the
+* `node_modules` store. The dep-cache packer must travel those sibling dirs with
+* the closure (their symlinks would dangle otherwise), and the yarn install path
+* must build them (the install links a sibling but does not build it).
+*
+* `collectInRepoSiblings` walks a starting `node_modules` (and transitively each
+* discovered sibling's `node_modules`), returning each in-repo sibling directory
+* once, repo-root-relative, in breadth-first discovery order. The starting
+* `node_modules` is a parameter so it serves pnpm + yarn-standalone (seeded at
+* `.kici/node_modules`) and yarn-workspace-member (seeded at the hoisted root
+* `node_modules`).
+*/
+/**
+* The directory yarn lays `.kici`'s dependencies into. A standalone `.kici`
+* (own lockfile, no parent workspace) gets `.kici/node_modules`; a workspace
+* member hoists everything to the repo-root `node_modules`, leaving no
+* `.kici/node_modules`.
+*/
+function resolveYarnNodeModulesRoot(repoRoot, kiciDir) {
+	const kiciNm = join(kiciDir, "node_modules");
+	return existsSync(kiciNm) ? kiciNm : join(repoRoot, "node_modules");
+}
+/**
+* Walk `seedNodeModules` (and transitively each in-repo sibling's
+* `node_modules`) collecting the repo-root-relative directories of workspace
+* siblings — package dirs that live inside the clone but outside `.kici/` and
+* outside the repo-root `node_modules/` store. Returns each dir once, in
+* discovery (BFS) order.
+*/
+async function collectInRepoSiblings(workDir, kiciDir, seedNodeModules = join(kiciDir, "node_modules")) {
+	const repoRoot = resolve(workDir);
+	const kiciResolved = resolve(kiciDir);
+	const rootNodeModules = resolve(join(workDir, "node_modules"));
+	const found = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [seedNodeModules];
+	while (queue.length > 0) {
+		const nmDir = queue.shift();
+		const real = await realpath(nmDir).catch(() => null);
+		if (!real || visited.has(real)) continue;
+		visited.add(real);
+		for (const target of await resolveNodeModulesLinks(nmDir)) {
+			if (!isInside(repoRoot, target)) continue;
+			if (isInside(kiciResolved, target) || isInside(rootNodeModules, target)) continue;
+			const rel = relative(workDir, target);
+			if (!found.has(rel)) {
+				found.add(rel);
+				queue.push(join(target, "node_modules"));
+			}
+		}
+	}
+	return [...found];
+}
+/** Resolve every package symlink target under a `node_modules` dir (descending one level into `@scope` dirs). */
+async function resolveNodeModulesLinks(nmDir) {
+	const targets = [];
+	for (const entry of await readdir(nmDir).catch(() => [])) {
+		if (entry.startsWith(".")) continue;
+		const entryPath = join(nmDir, entry);
+		if (entry.startsWith("@")) {
+			for (const scoped of await readdir(entryPath).catch(() => [])) {
+				const target = await resolveIfSymlink(join(entryPath, scoped));
+				if (target) targets.push(target);
+			}
+			continue;
+		}
+		const target = await resolveIfSymlink(entryPath);
+		if (target) targets.push(target);
+	}
+	return targets;
+}
+/** Return the real path of `p` if it is a symlink, else null. */
+async function resolveIfSymlink(p) {
+	try {
+		if (!(await lstat(p)).isSymbolicLink()) return null;
+		return await realpath(p);
+	} catch {
+		return null;
+	}
+}
+/** Whether `target` is `root` itself or a path inside it. */
+function isInside(root, target) {
+	const rel = relative(root, target);
+	return rel === "" || !rel.startsWith("..") && !rel.startsWith(`..${sep}`) && !isAbsoluteRel(rel);
+}
+function isAbsoluteRel(rel) {
+	return rel.length > 1 && rel[1] === ":";
+}
+//#endregion
 //#region src/execution/dep-installer.ts
 /**
 * Inline dependency installation for graceful degradation.
@@ -445,12 +557,14 @@ async function assertResolvableDeps(args) {
 * 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
+* The package manager is detected from the cloned repo (npm / pnpm / yarn); 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.
+* `workspace:` siblings. yarn classic (v1) is supported for registry
+* dependencies and version-range workspace siblings (which it links but does
+* not build, so the agent builds the in-repo closure after install). yarn
+* berry (v2+) is not yet supported.
 *
 * Security: the install runs with an isolated per-invocation cache/store
 * directory to prevent cache poisoning across build jobs — a malicious
@@ -499,7 +613,6 @@ async function installDeps(kiciDir, opts = {}) {
 		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,
@@ -519,6 +632,11 @@ async function installDeps(kiciDir, opts = {}) {
 			hasPrivateRegistry,
 			registryConfig
 		});
+		else if (packageManager === PackageManager.Yarn) await runYarnInstall({
+			kiciDir,
+			hasPrivateRegistry,
+			registryConfig
+		});
 		else await runNpmInstall({
 			kiciDir,
 			hasPrivateRegistry,
@@ -533,6 +651,7 @@ async function installDeps(kiciDir, opts = {}) {
 		await registryConfig.cleanup();
 	}
 	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot);
+	if (packageManager === PackageManager.Yarn) await buildYarnWorkspaceClosure(repoRoot, kiciDir);
 	const durationMs = Date.now() - startTime;
 	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
 	logger$2.info("Deps installed inline", {
@@ -620,6 +739,101 @@ async function runPnpmInstall(args) {
 		}).catch(() => {});
 	}
 }
+/** Pure: argv for `yarn install` with an isolated cache folder. */
+function buildYarnInstallArgs(cacheDir, hasPrivateRegistry) {
+	const a = [
+		"install",
+		"--cache-folder",
+		cacheDir,
+		"--non-interactive",
+		"--no-progress"
+	];
+	if (hasPrivateRegistry) a.push("--ignore-scripts");
+	return a;
+}
+/**
+* Run `yarn install` from `.kici/` with an isolated cache folder. yarn classic
+* reads the synthesized `.kici/.npmrc` (registry + `${VAR}` token expansion) for
+* private-registry auth. A workspace member hoists deps to the repo-root
+* node_modules; a standalone `.kici` gets `.kici/node_modules`. Not
+* `--frozen-lockfile` (resolved URLs in the lockfile may point at a different
+* registry than the synthesized `.npmrc`, e.g. localhost tunnel vs direct IP).
+*/
+async function runYarnInstall(args) {
+	await assertYarnAvailable();
+	const { nodeDir } = resolveNpm();
+	const cacheDir = await mkdtemp(join(tmpdir(), "kici-yarn-cache-"));
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const argv = buildYarnInstallArgs(cacheDir, args.hasPrivateRegistry);
+	try {
+		process.stderr.write(`[dep-installer:trace] running: yarn ${argv.join(" ")}\n`);
+		await execFileAsync("yarn", argv, {
+			cwd: args.kiciDir,
+			env,
+			timeout: INSTALL_TIMEOUT_MS,
+			maxBuffer: INSTALL_MAX_BUFFER
+		});
+	} finally {
+		await rm(cacheDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/** Throw an actionable error when the repo needs yarn but it is not installed. */
+async function assertYarnAvailable() {
+	try {
+		await execFileAsync("yarn", ["--version"], {
+			timeout: 3e4,
+			cwd: tmpdir()
+		});
+	} catch (e) {
+		throw new Error(`This repository uses yarn, but yarn is not available on this agent. Install yarn (e.g. \`corepack enable\`) or run on a container/Firecracker agent that bundles it. (${toErrorMessage(e)})`);
+	}
+}
+/**
+* Build the in-repo workspace siblings `.kici` depends on (yarn links them on
+* install but does not build them). Walks siblings from the resolved
+* node_modules root and runs each sibling's `build` script in leaf-first
+* (reverse-discovery) order with a clean env (no synthesized registry tokens).
+* Deep cross-sibling build chains may build out of strict topological order —
+* real `.kici` closures are shallow.
+*/
+async function buildYarnWorkspaceClosure(repoRoot, kiciDir) {
+	const siblings = await collectInRepoSiblings(repoRoot, kiciDir, resolveYarnNodeModulesRoot(repoRoot, kiciDir));
+	if (siblings.length === 0) return;
+	const { nodeDir } = resolveNpm();
+	const env = envWithNodeOnPath({}, nodeDir);
+	for (const rel of [...siblings].reverse()) {
+		const sibDir = join(repoRoot, rel);
+		if (!await siblingHasBuildScript(sibDir)) continue;
+		process.stderr.write(`[dep-installer:trace] building yarn sibling: yarn --cwd ${sibDir} run build\n`);
+		try {
+			await execFileAsync("yarn", [
+				"--cwd",
+				sibDir,
+				"run",
+				"build"
+			], {
+				cwd: repoRoot,
+				env,
+				timeout: INSTALL_TIMEOUT_MS,
+				maxBuffer: INSTALL_MAX_BUFFER
+			});
+		} catch (e) {
+			logSubprocessStreams(e, []);
+			throw new Error(`Failed to build .kici yarn workspace sibling ${rel}: ${describeExecError(e)}`);
+		}
+	}
+}
+/** Whether a sibling package.json declares a `build` script. */
+async function siblingHasBuildScript(sibDir) {
+	try {
+		return typeof JSON.parse(await readFile(join(sibDir, "package.json"), "utf-8")).scripts?.build === "string";
+	} catch {
+		return false;
+	}
+}
 /**
 * Build the in-repo dependency closure of the `.kici/` package so a
 * `workspace:` sibling's build output exists before the workflow that imports
@@ -663,7 +877,10 @@ function describeExecError(e) {
 /** Throw an actionable error when the repo needs pnpm but it is not installed. */
 async function assertPnpmAvailable() {
 	try {
-		await execFileAsync("pnpm", ["--version"], { timeout: 3e4 });
+		await execFileAsync("pnpm", ["--version"], {
+			timeout: 3e4,
+			cwd: tmpdir()
+		});
 	} 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)})`);
 	}

package/dist/provenance/attest.d.ts

@@ -0,0 +1,30 @@
+import { type KiciBundle } from '@kici-dev/engine/provenance/bundle';
+import type { OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import { type ProvenanceSubject } from './statement-builder.js';
+export interface AttestDeps {
+    /** P1.4 relay: returns a KiCI ID token bound to the current job. */
+    getIdToken: (opts: {
+        audience: string;
+    }) => Promise<OidcTokenResult>;
+    /** Upload the serialized bundle; returns the storage key it was written to. */
+    persist: (bundle: KiciBundle, subjectDigest: string) => Promise<string>;
+    builderVersions: {
+        'kici-agent': string;
+        'kici-orchestrator': string;
+    };
+    /** Injectable clock for deterministic tests; defaults to wall time. */
+    now?: () => string;
+}
+export interface AttestInput {
+    subject: ProvenanceSubject;
+    audience?: string;
+}
+export interface AttestResult {
+    storageKey: string;
+    bundle: KiciBundle;
+    subjectDigest: string;
+}
+export declare function attestProvenance(deps: AttestDeps, input: AttestInput): Promise<AttestResult>;
+/** Pick the primary digest (`sha256` preferred) as the storage-key discriminator. */
+export declare function subjectDigestString(subject: ProvenanceSubject): string;
+//# sourceMappingURL=attest.d.ts.map

package/dist/provenance/sign.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ephemeral-key DSSE signer for KiCI provenance (Mode A).
+ *
+ * Generates a fresh in-process ES256 keypair (never persisted), DSSE-signs the
+ * PAE of the statement bytes with the private half, and returns the envelope
+ * plus the public JWK. The public key travels in the bundle so the verifier can
+ * check the signature; the key needs no separate trust root because the bundle's
+ * identity JWT (verified against the Platform JWKS) anchors the whole package.
+ */
+import { type JWK } from 'jose';
+import { type DsseEnvelope } from '@kici-dev/engine/provenance/dsse';
+export interface SignedStatement {
+    envelope: DsseEnvelope;
+    /** Ephemeral public key as a JWK, with `kid` = its RFC 7638 thumbprint. */
+    publicJwk: JWK & {
+        kid: string;
+    };
+}
+/** DSSE-sign `statementBytes` with a fresh in-process ephemeral ES256 key. */
+export declare function signStatementDsse(payloadType: string, statementBytes: Uint8Array): Promise<SignedStatement>;
+//# sourceMappingURL=sign.d.ts.map

package/dist/provenance/statement-builder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Build a SLSA v1.0 in-toto provenance statement from the server-truth identity
+ * token claims plus the caller-supplied subject. The build context comes
+ * entirely from the JWT claims (Platform-minted, unforgeable), so the
+ * statement's identity equals the token's identity by construction.
+ */
+import { type KiciProvenanceStatement } from '@kici-dev/engine/provenance/schema';
+/** The KiCI identity-token claims the builder reads (Platform server-truth). */
+export interface ProvenanceTokenClaims {
+    iss: string;
+    repository?: string | null;
+    ref?: string | null;
+    sha?: string | null;
+    workflow_ref?: string | null;
+    kici_run_id: string;
+    kici_job_id: string;
+    orchestrator_id?: string | null;
+}
+/** Caller-supplied artifact subject: a name plus a lowercase-hex digest map. */
+export interface ProvenanceSubject {
+    name: string;
+    digest: Record<string, string>;
+}
+export interface BuildStatementInput {
+    tokenClaims: ProvenanceTokenClaims;
+    subject: ProvenanceSubject;
+    builderVersions: {
+        'kici-agent': string;
+        'kici-orchestrator': string;
+    };
+    /** ISO-8601 timestamp with offset. */
+    startedOn: string;
+    /** ISO-8601 timestamp with offset. */
+    finishedOn: string;
+}
+/** Build a KiCI SLSA v1.0 provenance statement (validates against the P1.1 schema). */
+export declare function buildProvenanceStatement(input: BuildStatementInput): KiciProvenanceStatement;
+//# sourceMappingURL=statement-builder.d.ts.map