@kici-dev/shared 0.1.9 → 0.1.11

package/dist/package-manager-types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Package-manager identity — the enum and pure helpers, with no filesystem
+ * dependency. Kept separate from `package-manager.ts` (which reads the disk to
+ * detect the manager) so browser-safe consumers — the engine protocol schemas
+ * and lock-file types the dashboard transitively imports — can reference the
+ * enum without pulling `node:fs` into a browser bundle.
+ */
+/** Supported package managers. */
+export declare enum PackageManager {
+    Npm = "npm",
+    Pnpm = "pnpm",
+    Yarn = "yarn"
+}
+/** All package-manager identifiers, for flag/schema validation. */
+export declare const PACKAGE_MANAGERS: readonly PackageManager[];
+/**
+ * Parse a raw string into a {@link PackageManager}, or `null` when it does not
+ * name a supported manager. Accepts bare names (`pnpm`) used by the CLI flag
+ * and the env-var / packageManager-field tiers.
+ */
+export declare function parsePackageManager(value: string): PackageManager | null;
+//# sourceMappingURL=package-manager-types.d.ts.map

package/dist/package-manager-types.js

@@ -0,0 +1,35 @@
+import "./chunk-gOLHoazu.js";
+//#region src/package-manager-types.ts
+/**
+* Package-manager identity — the enum and pure helpers, with no filesystem
+* dependency. Kept separate from `package-manager.ts` (which reads the disk to
+* detect the manager) so browser-safe consumers — the engine protocol schemas
+* and lock-file types the dashboard transitively imports — can reference the
+* enum without pulling `node:fs` into a browser bundle.
+*/
+/** Supported package managers. */
+let PackageManager = /* @__PURE__ */ function(PackageManager) {
+	PackageManager["Npm"] = "npm";
+	PackageManager["Pnpm"] = "pnpm";
+	PackageManager["Yarn"] = "yarn";
+	return PackageManager;
+}({});
+/** All package-manager identifiers, for flag/schema validation. */
+const PACKAGE_MANAGERS = Object.values(PackageManager);
+/**
+* Parse a raw string into a {@link PackageManager}, or `null` when it does not
+* name a supported manager. Accepts bare names (`pnpm`) used by the CLI flag
+* and the env-var / packageManager-field tiers.
+*/
+function parsePackageManager(value) {
+	switch (value) {
+		case "npm": return "npm";
+		case "pnpm": return "pnpm";
+		case "yarn": return "yarn";
+		default: return null;
+	}
+}
+//#endregion
+export { PACKAGE_MANAGERS, PackageManager, parsePackageManager };
+
+//# sourceMappingURL=package-manager-types.js.map

package/dist/package-manager.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Package-manager detection.
+ *
+ * Determines which package manager (npm / pnpm / yarn) a project relies on, so
+ * dependency operations use the manager that matches the rest of the user's
+ * repository instead of always assuming npm. Used by `kici init` (to generate a
+ * lockfile that matches the user's repo) and by the agent (to install `.kici/`
+ * dependencies with the manager that can resolve the repo's dependency graph,
+ * including pnpm/yarn `workspace:` siblings).
+ *
+ * The {@link PackageManager} enum + pure helpers live in the node-free
+ * `./package-manager-types.js` module and are re-exported here so existing
+ * `@kici-dev/shared/package-manager` consumers keep one import site.
+ */
+import { PackageManager } from './package-manager-types.js';
+export { PackageManager, PACKAGE_MANAGERS, parsePackageManager } from './package-manager-types.js';
+/** Map a detected manager to its install command argv (binary + args). */
+export declare function installCommand(pm: PackageManager): [string, 'install'];
+/**
+ * Detect the package manager the user's project relies on.
+ *
+ * Priority order (first match wins):
+ *   1. `packageManager` field in `<projectDir>/package.json` (Corepack
+ *      convention, e.g. `"packageManager": "pnpm@9.x"`). Only the name before
+ *      `@` is parsed; an unrecognized name falls through.
+ *   2. A lockfile in the project root (`pnpm-lock.yaml` > `yarn.lock` >
+ *      `package-lock.json`).
+ *   3. The `npm_config_user_agent` env var (set by `pnpm dlx` / `yarn dlx` /
+ *      `npx`); the leading `<name>/` segment names the manager.
+ *   4. Default to npm when nothing matches, so we never guess wrong and emit a
+ *      lockfile the user did not ask for.
+ *
+ * @param projectDir - The project root to inspect.
+ */
+export declare function detectPackageManager(projectDir: string): Promise<PackageManager>;
+/**
+ * Detect the package manager from a directory's **committed manifests only** —
+ * tiers 1 (`packageManager` field) and 2 (lockfile). Returns `null` when the
+ * directory carries no package-manager signal, so callers can distinguish
+ * "explicitly npm" from "no signal".
+ *
+ * This deliberately excludes the `npm_config_user_agent` tier: a consumer
+ * inspecting a cloned repository (the agent) must key off the repo's own files,
+ * not the ambient env of the process that happens to be reading them.
+ */
+export declare function detectPackageManagerFromManifests(projectDir: string): Promise<PackageManager | null>;
+/**
+ * Synchronous {@link detectPackageManager}. Used by the compiler's lock-file
+ * generation, which is synchronous; identical tiering and precedence.
+ */
+export declare function detectPackageManagerSync(projectDir: string): PackageManager;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/package-manager.js

@@ -0,0 +1,131 @@
+import "./chunk-gOLHoazu.js";
+import { PACKAGE_MANAGERS, PackageManager, parsePackageManager } from "./package-manager-types.js";
+import { access, readFile } from "node:fs/promises";
+import { accessSync, readFileSync } from "node:fs";
+import path from "node:path";
+//#region src/package-manager.ts
+/**
+* Package-manager detection.
+*
+* Determines which package manager (npm / pnpm / yarn) a project relies on, so
+* dependency operations use the manager that matches the rest of the user's
+* repository instead of always assuming npm. Used by `kici init` (to generate a
+* lockfile that matches the user's repo) and by the agent (to install `.kici/`
+* dependencies with the manager that can resolve the repo's dependency graph,
+* including pnpm/yarn `workspace:` siblings).
+*
+* The {@link PackageManager} enum + pure helpers live in the node-free
+* `./package-manager-types.js` module and are re-exported here so existing
+* `@kici-dev/shared/package-manager` consumers keep one import site.
+*/
+/** Map a detected manager to its install command argv (binary + args). */
+function installCommand(pm) {
+	return [pm, "install"];
+}
+/** Lockfile basenames mapped to the manager that produces them, in priority order. */
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"]
+];
+/**
+* Detect the package manager the user's project relies on.
+*
+* Priority order (first match wins):
+*   1. `packageManager` field in `<projectDir>/package.json` (Corepack
+*      convention, e.g. `"packageManager": "pnpm@9.x"`). Only the name before
+*      `@` is parsed; an unrecognized name falls through.
+*   2. A lockfile in the project root (`pnpm-lock.yaml` > `yarn.lock` >
+*      `package-lock.json`).
+*   3. The `npm_config_user_agent` env var (set by `pnpm dlx` / `yarn dlx` /
+*      `npx`); the leading `<name>/` segment names the manager.
+*   4. Default to npm when nothing matches, so we never guess wrong and emit a
+*      lockfile the user did not ask for.
+*
+* @param projectDir - The project root to inspect.
+*/
+async function detectPackageManager(projectDir) {
+	const fromManifests = await detectPackageManagerFromManifests(projectDir);
+	if (fromManifests) return fromManifests;
+	const fromUserAgent = parseUserAgent(process.env.npm_config_user_agent);
+	if (fromUserAgent) return fromUserAgent;
+	return "npm";
+}
+/**
+* Detect the package manager from a directory's **committed manifests only** —
+* tiers 1 (`packageManager` field) and 2 (lockfile). Returns `null` when the
+* directory carries no package-manager signal, so callers can distinguish
+* "explicitly npm" from "no signal".
+*
+* This deliberately excludes the `npm_config_user_agent` tier: a consumer
+* inspecting a cloned repository (the agent) must key off the repo's own files,
+* not the ambient env of the process that happens to be reading them.
+*/
+async function detectPackageManagerFromManifests(projectDir) {
+	const fromField = parsePackageManagerField(await readPackageJson(projectDir));
+	if (fromField) return fromField;
+	for (const [file, pm] of LOCKFILES) if (await fileExists(path.join(projectDir, file))) return pm;
+	return null;
+}
+/**
+* Synchronous {@link detectPackageManager}. Used by the compiler's lock-file
+* generation, which is synchronous; identical tiering and precedence.
+*/
+function detectPackageManagerSync(projectDir) {
+	const fromField = parsePackageManagerField(readPackageJsonSync(projectDir));
+	if (fromField) return fromField;
+	for (const [file, pm] of LOCKFILES) if (fileExistsSync(path.join(projectDir, file))) return pm;
+	const fromUserAgent = parseUserAgent(process.env.npm_config_user_agent);
+	if (fromUserAgent) return fromUserAgent;
+	return "npm";
+}
+/** Tier 1: parse the Corepack `packageManager` field, if present. */
+function parsePackageManagerField(content) {
+	if (content === null) return null;
+	try {
+		const pkg = JSON.parse(content);
+		if (typeof pkg.packageManager !== "string") return null;
+		return parsePackageManager(pkg.packageManager.split("@", 1)[0]);
+	} catch {
+		return null;
+	}
+}
+/** Tier 3: the `npm_config_user_agent` env var, whose leading segment names the manager. */
+function parseUserAgent(userAgent) {
+	if (!userAgent) return null;
+	return parsePackageManager(userAgent.split("/", 1)[0]);
+}
+async function readPackageJson(projectDir) {
+	try {
+		return await readFile(path.join(projectDir, "package.json"), "utf-8");
+	} catch {
+		return null;
+	}
+}
+function readPackageJsonSync(projectDir) {
+	try {
+		return readFileSync(path.join(projectDir, "package.json"), "utf-8");
+	} catch {
+		return null;
+	}
+}
+async function fileExists(target) {
+	try {
+		await access(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function fileExistsSync(target) {
+	try {
+		accessSync(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { PACKAGE_MANAGERS, PackageManager, detectPackageManager, detectPackageManagerFromManifests, detectPackageManagerSync, installCommand, parsePackageManager };
+
+//# sourceMappingURL=package-manager.js.map

package/dist/package-manager.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=package-manager.test.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/shared",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
   "keywords": [
     "kici",
@@ -65,6 +65,14 @@
     "./db-collation": {
       "import": "./dist/db-collation.js",
       "types": "./dist/db-collation.d.ts"
+    },
+    "./package-manager": {
+      "import": "./dist/package-manager.js",
+      "types": "./dist/package-manager.d.ts"
+    },
+    "./package-manager-types": {
+      "import": "./dist/package-manager-types.js",
+      "types": "./dist/package-manager-types.d.ts"
     }
   },
   "dependencies": {

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/shared@0.1.9",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.9/2a0fe48d-9ace-447e-bf38-52dc8ec9bacf",
+  "name": "@kici-dev/shared@0.1.11",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.11/93edde48-354c-4bb9-91a7-77d0ffd95743",
   "creationInfo": {
-    "created": "2026-05-26T16:48:53Z",
+    "created": "2026-05-27T16:18:10Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -947,7 +947,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/shared",
-      "versionInfo": "0.1.9",
+      "versionInfo": "0.1.11",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -958,7 +958,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.9"
+          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.11"
         }
       ],
       "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",