@kici-dev/agent 0.1.9 → 0.1.11

package/dist/execution/dep-installer.d.ts

@@ -1,17 +1,22 @@
 /**
  * Inline dependency installation for graceful degradation.
  *
- * When dep cache is unavailable or download fails, the agent falls back
- * to running npm install directly.
+ * When the dep cache is unavailable or a download fails, the agent installs
+ * `.kici/` dependencies directly with the repository's package manager.
  *
- * Only npm is supported — it ships with every Node.js installation.
- * .kici/package.json is required — its presence signals deps should be installed.
+ * 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: npm runs with an isolated per-invocation cache 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 — npm runs with
- * `--ignore-scripts` whenever a private registry is configured.
+ * 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.
  */
 import { type NpmRegistrySpec } from './npm-registry-config.js';
 export interface InstallDepsOptions {
@@ -21,24 +26,27 @@ export interface InstallDepsOptions {
     installEnvSecrets?: Record<string, string>;
     /** Short job-scoped nonce — used as suffix on synthesized env-var names. */
     jobIdShort?: string;
+    /**
+     * Clone root (repo root). Package-manager detection runs against it first,
+     * then falls back to `kiciDir`. Defaults to `dirname(kiciDir)`.
+     */
+    repoRoot?: string;
 }
 /**
- * Install dependencies inline using npm.
+ * Install `.kici/` dependencies inline with the repo's package manager.
  *
- * Falls back to this when the dep cache is unavailable or download fails.
+ * 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.
  *
- * npm runs with an isolated cache directory (created in os.tmpdir()) to prevent
- * cache poisoning between build jobs. The cache 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.
  *
- * If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, the helper
- * synthesizes a job-scoped `.kici/.npmrc` overlay for the install, restores
- * the original file in `finally`, and runs npm with `--ignore-scripts` so
- * lifecycle scripts in 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 configuration. When absent,
- *                  behavior is identical to the pre-private-registry version.
+ * @param kiciDir - Path to the `.kici/` directory containing package.json.
+ * @param opts    - Optional registry / installEnv / repoRoot configuration.
  */
 export declare function installDeps(kiciDir: string, opts?: InstallDepsOptions): Promise<void>;
 //# sourceMappingURL=dep-installer.d.ts.map

package/dist/execution/dep-packer.d.ts

@@ -1,22 +1,29 @@
 /**
- * Node_modules tarball creation for build agents.
+ * Dependency tarball creation for build agents.
  *
- * After installing dependencies in .kici/, packs node_modules
- * into a gzip tarball for upload to the dep cache.
+ * After installing dependencies the build agent packs the dependency closure
+ * into a gzip tarball for upload to the dep cache. The closure is packed
+ * **repo-root-relative** (cwd = the clone root) so restore is a single layout
+ * regardless of package manager:
  *
- * Uses tar.gz format (Node.js built-in zlib, no external binary needed).
- * Uses portable mode to strip user/group info for cross-machine consistency.
+ * - npm / yarn: just `.kici/node_modules`.
+ * - pnpm: `.kici/node_modules` plus the repo-root `node_modules/.pnpm` virtual
+ *   store and the in-repo `workspace:` sibling package directories `.kici`
+ *   depends on (with their built output). pnpm lays `.kici/node_modules` out as
+ *   symlinks into the root store and into sibling dirs that live outside
+ *   `.kici/`, so packing `.kici/node_modules` alone would capture dangling
+ *   links — the store and siblings must travel together.
+ *
+ * Uses tar.gz (Node.js built-in zlib, no external binary) in portable mode to
+ * strip user/group info for cross-machine consistency; symlinks are preserved
+ * as symlinks so the pnpm link graph restores intact.
  */
 /**
- * Pack node_modules into a gzip tarball and compute its SHA-256 hash.
- *
- * Creates a tar.gz archive of the `node_modules/` directory relative to
- * kiciDir. The tarball is created in-memory and returned as a Buffer
- * along with its content hash.
+ * Pack the dependency closure into a gzip tarball and compute its SHA-256 hash.
  *
- * @param kiciDir - Path to the .kici/ directory containing node_modules/
- * @returns Object with tarball Buffer and SHA-256 hash string
- * @throws Error if node_modules/ does not exist in kiciDir
+ * @param kiciDir - Path to the `.kici/` directory containing node_modules/.
+ * @returns Object with the tarball Buffer and its SHA-256 hash string.
+ * @throws Error if `.kici/node_modules` does not exist.
  */
 export declare function packNodeModules(kiciDir: string): Promise<{
     tarball: Buffer;

package/dist/execution/dep-restore.d.ts

@@ -69,13 +69,17 @@ export declare function excludeScratchFromGit(repoWorkDir: string): Promise<void
  */
 export declare function resolveOrchestratorUrl(url: string): string;
 /**
- * Restore dependencies from a cached tarball.
+ * Restore dependencies from a cached tarball into the cloned repo.
  *
- * For HTTP/HTTPS URLs: uses a streaming pipeline (response -> hash -> gunzip -> tar)
- * with a 5-minute timeout and up to 2 retries. This avoids buffering entire tarballs
- * in memory, eliminating memory spikes proportional to tarball size.
+ * The tarball is packed repo-root-relative (see `dep-packer.ts`): every manager
+ * carries `.kici/node_modules`; pnpm additionally carries the root
+ * `node_modules/.pnpm` store and the in-repo workspace siblings `.kici` resolves.
+ * Restore extracts into a scratch dir, then moves each entry into place — one
+ * code path for all managers.
  *
- * For file:// URLs: uses a buffer-based approach (local, no streaming benefit).
+ * For HTTP/HTTPS URLs: a streaming pipeline (response -> hash -> gunzip -> tar)
+ * with a 5-minute timeout and up to 2 retries avoids buffering whole tarballs.
+ * For file:// URLs: a buffer-based approach (local, no streaming benefit).
  *
  * @param workDir - Root directory of the cloned repository
  * @param depsUrl - URL to the dependency tarball (http://, https://, or file://)

package/dist/execution/validate-kici-deps.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+import { PackageManager } from '@kici-dev/shared/package-manager';
+/** Local-protocol specifier prefixes that resolve against the filesystem. */
+export declare enum LocalDepProtocol {
+    Workspace = "workspace:",
+    File = "file:",
+    Link = "link:",
+    Portal = "portal:"
+}
+/** A dependency whose specifier uses a local (filesystem) protocol. */
+export interface LocalProtocolDep {
+    name: string;
+    spec: string;
+    protocol: LocalDepProtocol;
+}
+interface PackageJsonShape {
+    [field: string]: unknown;
+}
+/**
+ * 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.
+ */
+export declare function findLocalProtocolDeps(pkg: PackageJsonShape): LocalProtocolDep[];
+/**
+ * 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).
+ */
+export declare function kiciHasLocalProtocolDeps(kiciDir: string): Promise<boolean>;
+/** Build the actionable error for unresolvable local-protocol dependencies. */
+export declare function formatUnresolvableDepError(offenders: readonly LocalProtocolDep[], packageManager: PackageManager): string;
+/**
+ * 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.
+ */
+export declare function assertResolvableDeps(args: {
+    kiciDir: string;
+    repoRoot: string;
+    packageManager: PackageManager;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=validate-kici-deps.d.ts.map

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { loadConfig, type AppConfig } from './config.js';
+export { installDeps, type InstallDepsOptions } from './execution/dep-installer.js';
+export { findLocalProtocolDeps, assertResolvableDeps, formatUnresolvableDepError, kiciHasLocalProtocolDeps, LocalDepProtocol, type LocalProtocolDep, } from './execution/validate-kici-deps.js';
 //# sourceMappingURL=index.d.ts.map