feat: add npm cache ownership preflight check (#462)

Detect root-owned files in ~/.npm before running npm install.
A previous `sudo npm install` leaves root-owned cache files that cause
EACCES permission errors on subsequent installs. The check runs in both
the create and deploy preflight paths, and gives users the exact fix
command (sudo chown -R $(whoami) ~/.npm). Skipped on Windows.

Also fixes rollup high severity vulnerability (GHSA-mw96-cpmx-2vgc).

Co-authored-by: Abhimanyu Siwach <siwabhi@amazon.com>

Author: siwachabhi

src/cli/external-requirements/__tests__/checks-extended.test.ts

@@ -2,6 +2,8 @@ import type { AgentCoreProjectSpec, DirectoryPath, FilePath } from '../../../sch
 import {
   checkDependencyVersions,
   checkNodeVersion,
+  checkNpmCacheOwnership,
+  formatNpmCacheError,
   formatVersionError,
   requiresContainerRuntime,
   requiresUv,
@@ -174,6 +176,44 @@ describe('checkNodeVersion', () => {
   });
 });
 
+describe('checkNpmCacheOwnership', () => {
+  it('returns a result with expected structure', async () => {
+    const result = await checkNpmCacheOwnership();
+    expect(result).toHaveProperty('satisfied');
+    expect(result).toHaveProperty('owner');
+    expect(result).toHaveProperty('cacheDir');
+    expect(result.cacheDir).toContain('.npm');
+  });
+
+  it('is satisfied when cache is owned by current user', async () => {
+    // In a normal test environment, ~/.npm should be owned by the current user
+    const result = await checkNpmCacheOwnership();
+    expect(result.satisfied).toBe(true);
+  });
+});
+
+describe('formatNpmCacheError', () => {
+  it('includes cache directory path', () => {
+    const msg = formatNpmCacheError({ satisfied: false, owner: 'root', cacheDir: '/home/user/.npm' });
+    expect(msg).toContain('/home/user/.npm');
+  });
+
+  it('includes the wrong owner name', () => {
+    const msg = formatNpmCacheError({ satisfied: false, owner: 'root', cacheDir: '/home/user/.npm' });
+    expect(msg).toContain('root');
+  });
+
+  it('includes the fix command', () => {
+    const msg = formatNpmCacheError({ satisfied: false, owner: 'root', cacheDir: '/home/user/.npm' });
+    expect(msg).toContain('sudo chown -R $(whoami)');
+  });
+
+  it('mentions sudo npm install as likely cause', () => {
+    const msg = formatNpmCacheError({ satisfied: false, owner: 'root', cacheDir: '/home/user/.npm' });
+    expect(msg).toContain('sudo npm install');
+  });
+});
+
 describe('checkDependencyVersions', () => {
   it('passes when node meets requirements and no uv needed', async () => {
     const project: AgentCoreProjectSpec = {
@@ -190,6 +230,20 @@ describe('checkDependencyVersions', () => {
     expect(result.uvCheck).toBeNull();
   });
 
+  it('includes npmCacheCheck in result', async () => {
+    const project: AgentCoreProjectSpec = {
+      name: 'Test',
+      version: 1,
+      agents: [],
+      memories: [],
+      credentials: [],
+    };
+
+    const result = await checkDependencyVersions(project);
+    expect(result.npmCacheCheck).toBeDefined();
+    expect(result.npmCacheCheck.cacheDir).toContain('.npm');
+  });
+
   it('checks uv when project has CodeZip agents', async () => {
     const project: AgentCoreProjectSpec = {
       name: 'Test',

src/cli/external-requirements/checks.ts

@@ -5,6 +5,9 @@ import { checkSubprocess, isWindows, runSubprocessCapture } from '../../lib';
 import type { AgentCoreProjectSpec, TargetLanguage } from '../../schema';
 import { detectContainerRuntime } from './detect';
 import { AWS_CLI_MIN_VERSION, NODE_MIN_VERSION, formatSemVer, parseSemVer, semVerGte } from './versions';
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 
 /**
  * Result of a version check.
@@ -150,6 +153,66 @@ export function formatVersionError(result: VersionCheckResult): string {
   return `${result.binary} ${result.current} is below minimum required version ${result.required}`;
 }
 
+/**
+ * Result of checking npm cache directory ownership.
+ */
+export interface NpmCacheCheckResult {
+  /** true when the cache dir doesn't exist or is owned by the current user. */
+  satisfied: boolean;
+  /** Owner of ~/.npm, or null if the directory doesn't exist. */
+  owner: string | null;
+  /** The cache directory path that was checked. */
+  cacheDir: string;
+}
+
+/**
+ * Check that the npm cache directory (~/.npm) is owned by the current user.
+ *
+ * A previous `sudo npm install` can leave root-owned files in the cache,
+ * causing EACCES errors on subsequent `npm install` runs.
+ * Skipped on Windows where file ownership semantics differ.
+ */
+export async function checkNpmCacheOwnership(): Promise<NpmCacheCheckResult> {
+  const cacheDir = join(homedir(), '.npm');
+
+  // Skip on Windows - file ownership model is different
+  if (isWindows) {
+    return { satisfied: true, owner: null, cacheDir };
+  }
+
+  try {
+    const stats = await stat(cacheDir);
+    const currentUid = process.getuid?.();
+    if (currentUid === undefined) {
+      // getuid not available (e.g. some non-POSIX runtimes) — skip check
+      return { satisfied: true, owner: null, cacheDir };
+    }
+
+    if (stats.uid !== currentUid) {
+      // Resolve owner name for the error message
+      const ownerResult = await runSubprocessCapture('id', ['-un', String(stats.uid)]);
+      const owner = ownerResult.code === 0 ? ownerResult.stdout.trim() : `uid=${stats.uid}`;
+      return { satisfied: false, owner, cacheDir };
+    }
+
+    return { satisfied: true, owner: null, cacheDir };
+  } catch {
+    // Directory doesn't exist yet — not a problem
+    return { satisfied: true, owner: null, cacheDir };
+  }
+}
+
+/**
+ * Format an npm cache ownership failure as a user-friendly error message.
+ */
+export function formatNpmCacheError(result: NpmCacheCheckResult): string {
+  return (
+    `npm cache directory (${result.cacheDir}) is owned by '${result.owner}' instead of the current user. ` +
+    `This was likely caused by a previous 'sudo npm install'. ` +
+    `Fix: sudo chown -R $(whoami) ${result.cacheDir}`
+  );
+}
+
 /**
  * Check if the project has any Python CodeZip agents that require uv.
  */
@@ -171,6 +234,7 @@ export interface DependencyCheckResult {
   passed: boolean;
   nodeCheck: VersionCheckResult;
   uvCheck: VersionCheckResult | null;
+  npmCacheCheck: NpmCacheCheckResult;
   containerRuntimeAvailable: boolean;
   errors: string[];
 }
@@ -198,6 +262,12 @@ export async function checkDependencyVersions(projectSpec: AgentCoreProjectSpec)
     }
   }
 
+  // Check npm cache ownership (root-owned cache causes EACCES on npm install)
+  const npmCacheCheck = await checkNpmCacheOwnership();
+  if (!npmCacheCheck.satisfied) {
+    errors.push(formatNpmCacheError(npmCacheCheck));
+  }
+
   // Check container runtime only if there are Container agents (warn only, not error)
   let containerRuntimeAvailable = true;
   if (requiresContainerRuntime(projectSpec)) {
@@ -213,6 +283,7 @@ export async function checkDependencyVersions(projectSpec: AgentCoreProjectSpec)
     passed: errors.length === 0,
     nodeCheck,
     uvCheck,
+    npmCacheCheck,
     containerRuntimeAvailable,
     errors,
   };
@@ -291,6 +362,14 @@ export async function checkCreateDependencies(
     errors.push("'npm' is required. Install Node.js from https://nodejs.org/");
   }
 
+  // Check npm cache ownership (root-owned cache causes EACCES on npm install)
+  if (npmAvailable) {
+    const npmCacheCheck = await checkNpmCacheOwnership();
+    if (!npmCacheCheck.satisfied) {
+      errors.push(formatNpmCacheError(npmCacheCheck));
+    }
+  }
+
   // Check aws (warn if missing)
   const awsAvailable = await checkBinaryAvailable('aws');
   checks.push({

src/cli/external-requirements/index.ts

@@ -12,13 +12,16 @@ export {
   checkNodeVersion,
   checkUvVersion,
   checkAwsCliVersion,
+  checkNpmCacheOwnership,
   getAwsLoginGuidance,
   formatVersionError,
+  formatNpmCacheError,
   requiresUv,
   requiresContainerRuntime,
   checkDependencyVersions,
   checkCreateDependencies,
   type VersionCheckResult,
+  type NpmCacheCheckResult,
   type DependencyCheckResult,
   type CheckSeverity,
   type CliToolCheck,