age-install 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cinfinit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# age-install
+
+[![NPM version](https://img.shields.io/npm/v/age-install.svg?style=flat)](https://www.npmjs.com/package/age-install) [![NPM downloads](https://img.shields.io/npm/dm/age-install.svg?style=flat)](https://npmjs.org/package/age-install)
+
+> Because "trust me, it's fine" isn't a security strategy.
+
+Delay npm package installations until they reach a minimum age, protecting against supply chain attacks.
+
+---
+
+## The Problem
+
+Hackers love publishing malicious packages. You know what they love more? When those packages get taken down within an hour. So let's not install anything fresh out of the oven. Age-install waits until packages reach a certain age (in **minutes**) before letting them in.
+
+## Installation
+
+```bash
+npm install -g age-install
+```
+
+Or ride the `npx` wave:
+
+```bash
+npx age-install install react
+```
+
+## Quick Start
+
+```bash
+# Install with age check (default: 60 min minimum)
+age-install install react lodash
+
+# Check packages WITHOUT installing (generate report)
+age-install check react lodash
+
+# Check ALL dependencies in package.json
+age-install check
+
+# Add a package (like npm add, but safer)
+age-install add typescript
+
+# Bypass everything (you've been warned)
+age-install install react --force
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `install [pkgs]` | Install packages with safety checks |
+| `add <pkgs>` | Add packages to package.json with safety checks |
+| `check [pkgs]` | Check packages and generate report (no install) |
+| `exec -- <cmd>` | Run any npm command (passthrough) |
+| `cache` | Manage timestamp cache |
+
+## Options
+
+| Flag | What it does | Default |
+|------|-------------|---------|
+| `-m, --minimum-age <min>` | Minimum age in minutes before installing | 60 |
+| `-e, --exclude <pkg>` | Skip age check for these | none |
+| `-v, --verbose` | See what age-install is thinking | false |
+| `-f, --force` | Install without asking | false |
+| `-r, --report` | Save report to JSON file | false |
+| `--report-file <path>` | Custom report file path | age-install-report-YYYY-MM-DD.json |
+| `-c, --clear` | Clear the timestamp cache | false |
+| `-h, --help` | You're reading it | - |
+| `-V, --version` | Spoiler: still v0.1.0 | - |
+
+## Configuration
+
+### package.json
+
+```json
+{
+  "ageInstall": {
+    "minimumReleaseAge": 60,  // minutes
+    "minimumReleaseAgeExclude": ["webpack", "vite"]
+  }
+}
+```
+
+### .npmrc
+
+```
+age-install.minimumReleaseAge=60     # minutes
+age-install.minimumReleaseAgeExclude=webpack,vite
+```
+
+### Environment
+
+```bash
+AGE_INSTALL_MIN_AGE=60     # minutes
+AGE_INSTALL_EXCLUDE=webpack,vite
+```
+
+**Priority:** CLI args → Environment → Config file → Defaults
+
+## Exclusion Patterns
+
+Not everything needs the waiting room:
+
+```json
+{
+  "ageInstall": {
+    "minimumReleaseAgeExclude": [
+      "webpack",           // Exact match - webpack trusts webpack
+      "@babel/core",      // Scoped packages work too
+      "^eslint",           // Regex - matches eslint, eslint-config-*
+      "@types/*"           // Wildcard - all @types/* get a pass
+    ]
+  }
+}
+```
+
+## Check Command (Report Mode)
+
+The `check` command validates packages without installing. Perfect for CI/CD pipelines or auditing.
+
+```bash
+# Check specific packages
+age-install check react lodash express
+
+# Check all deps in package.json
+age-install check
+
+# Generate report and save to JSON file
+age-install check react lodash --report
+
+# Custom report file path
+age-install check --report --report-file ./my-report.json
+```
+
+**Example console output:**
+```
+📋 Checking 3 package(s)...
+
+✅ Safe to install (old enough):
+   - react@19.2.6 (207.8 hours old)
+   - lodash@4.18.1 (1043.1 hours old)
+
+⚠️  Too new (would be blocked):
+   - express@5.0.0 (15 minutes old, min: 60 min)
+
+⏭️  Excluded (no checks performed):
+   - webpack
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 Summary: 2 safe, 1 blocked, 1 excluded
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📄 Report saved to: age-install-report-2026-05-15.json
+```
+
+**Example JSON report file:**
+```json
+{
+  "generated": "2026-05-15T08:30:00.000Z",
+  "minimumAge": 60,
+  "source": "command-line",
+  "summary": {
+    "safe": 2,
+    "blocked": 1,
+    "excluded": 1,
+    "total": 4
+  },
+  "safe": [
+    {
+      "name": "react",
+      "version": "19.2.6",
+      "fullSpec": "react@19.2.6",
+      "ageMinutes": 12468,
+      "timestamp": "2026-05-06T16:16:47.653Z"
+    }
+  ],
+  "blocked": [
+    {
+      "name": "express",
+      "version": "5.0.0",
+      "fullSpec": "express@5.0.0",
+      "ageMinutes": 15,
+      "ageFormatted": "15 minutes",
+      "timestamp": "2026-05-15T08:15:00.000Z"
+    }
+  ],
+  "excluded": [
+    { "name": "webpack" }
+  ]
+}
+```
+
+## Features
+
+- **Scoped packages?** Yup. `@babel/core`, `@types/react`, all good.
+- **Version ranges?** Bring it. `react@^18`, `lodash@~4.17`, `express@^4`.
+- **Partial versions?** We got you. `express@^4` resolves to the real thing.
+- **Zero dependencies?** True story. Pure Node.js.
+- **JSON reports?** You bet. Perfect for CI/CD artifacts.
+
+## Why Not Just Use pnpm?
+
+pnpm v10.16 added this natively. Nice, right? But what if you're already using npm? Or yarn? Age-install has your back across the ecosystem.
+
+## About the Author
+
+Built by **[cinfinit](https://github.com/cinfinit)** who's tired of the "just installed a malicious package" Slack messages at 3 AM.
+
+This started as a "let's quickly check if any of our deps were published today" script and turned into this. If you find it useful, great. If not, at least you now know what `minimumReleaseAge` is for in pnpm.
+
+**Made with:** VS Code, 0 caffeine, and a healthy distrust of packages published in the last hour.

package/bin/age-install.js

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { loadConfig, mergeCliConfig } = require('../src/config');
+const { validatePackages } = require('../src/validator');
+
+const CWD = process.cwd();
+const ARGS = process.argv.slice(2);
+
+const COLORS = {
+  red: (text) => `\x1b[31m${text}\x1b[0m`,
+  green: (text) => `\x1b[32m${text}\x1b[0m`,
+  yellow: (text) => `\x1b[33m${text}\x1b[0m`,
+  cyan: (text) => `\x1b[36m${text}\x1b[0m`,
+  dim: (text) => `\x1b[2m${text}\x1b[0m`,
+};
+
+function formatAge(ageMinutes) {
+  if (ageMinutes > 60) {
+    return `${(ageMinutes / 60).toFixed(1)} hours`;
+  }
+  return `${Math.round(ageMinutes)} minutes`;
+}
+
+function printBlockedPackages(packages, minAge) {
+  for (const pkg of packages) {
+    console.log(`   - ${pkg.fullSpec} - published ${formatAge(pkg.ageMinutes)} ago (min: ${minAge} min)`);
+  }
+}
+
+function parseArgs(args) {
+  const result = {
+    command: null,
+    packages: [],
+    options: {},
+  };
+
+  const COMMANDS = ['install', 'add', 'check', 'exec', 'cache'];
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--') {
+      break;
+    }
+
+    if (arg.startsWith('-')) {
+      switch (arg) {
+        case '-h':
+        case '--help':
+          result.options.help = true;
+          break;
+        case '-V':
+        case '--version':
+          result.options.version = true;
+          break;
+        case '-v':
+        case '--verbose':
+          result.options.verbose = true;
+          break;
+        case '-f':
+        case '--force':
+          result.options.force = true;
+          break;
+        case '-m':
+        case '--minimum-age':
+          result.options.minimumAge = parseInt(args[++i], 10);
+          break;
+        case '-e':
+        case '--exclude':
+          result.options.exclude = args[++i];
+          break;
+        case '-c':
+        case '--clear':
+          result.options.clear = true;
+          break;
+        case '--report':
+          result.options.report = true;
+          break;
+        case '--report-file':
+          result.options.reportFile = args[++i];
+          break;
+      }
+      i++;
+      continue;
+    }
+
+    if (COMMANDS.includes(arg)) {
+      result.command = arg;
+      i++;
+      continue;
+    }
+
+    result.packages.push(arg);
+    i++;
+  }
+
+  if (result.packages.length > 0 && !result.command) {
+    result.command = 'install';
+  }
+
+  return result;
+}
+
+async function installWithChecks(packages, options, saveFlag = false) {
+  const config = mergeCliConfig(loadConfig(CWD), options);
+
+  if (config.force) {
+    runNpm(['install', ...packages, saveFlag]);
+    return;
+  }
+
+  const results = await validatePackages(packages, config, CWD);
+  const allowed = results.filter((r) => r.allowed);
+  const blocked = results.filter((r) => !r.allowed);
+
+  if (blocked.length > 0) {
+    console.error(COLORS.red('\n[X] Install blocked - unsafe packages:'));
+    printBlockedPackages(blocked, config.minimumReleaseAge);
+    console.log(COLORS.cyan('\n[?] To allow these packages:'));
+    console.log(`   - Add to exclusion list: age-install install ${blocked.map((r) => r.name).join(' ')} -e ${blocked.map((r) => r.name).join(',')}`);
+    console.log(`   - Lower threshold: age-install install ${packages.join(' ')} -m 0`);
+    console.log(`   - Force install: age-install install ${packages.join(' ')} -f`);
+    process.exit(1);
+  }
+
+  console.log(COLORS.green(`\n[OK] All ${allowed.length} packages passed safety checks`));
+  runNpm(['install', ...packages, saveFlag]);
+}
+
+async function installFromPackageJson(config) {
+  const pkgPath = path.join(CWD, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    console.error(COLORS.red('No package.json found'));
+    process.exit(1);
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch {
+    console.error(COLORS.red('Error reading package.json'));
+    process.exit(1);
+  }
+
+  const deps = [
+    ...Object.keys(pkg.dependencies || {}),
+    ...Object.keys(pkg.devDependencies || {}),
+  ];
+
+  if (deps.length === 0) {
+    console.log(COLORS.yellow('No dependencies found in package.json'));
+    return;
+  }
+
+  console.log(COLORS.cyan(`Checking ${deps.length} dependencies...`));
+
+  const packages = deps.map((dep) => {
+    const version = pkg.dependencies?.[dep] || pkg.devDependencies?.[dep] || '';
+    return version ? `${dep}@${version}` : dep;
+  });
+
+  const results = await validatePackages(packages, config, CWD);
+
+  const safe = results.filter((r) => r.allowed && r.reason !== 'excluded');
+  const blocked = results.filter((r) => !r.allowed);
+  const excluded = results.filter((r) => r.reason === 'excluded');
+
+  if (excluded.length > 0) {
+    console.log(COLORS.cyan('\n[>>] Excluded packages (no checks):'));
+    excluded.forEach((r) => console.log(`   - ${r.name}`));
+  }
+
+  if (blocked.length > 0) {
+    console.log(COLORS.yellow('\n[!] Skipped packages (too new):'));
+    printBlockedPackages(blocked, config.minimumReleaseAge);
+  }
+
+  const toInstall = safe.map((r) => r.fullSpec);
+
+  if (toInstall.length > 0) {
+    console.log(COLORS.green(`\n[OK] Installing ${toInstall.length} safe packages...`));
+    runNpm(['install', ...toInstall]);
+  } else {
+    console.log(COLORS.yellow('\n[--] No packages to install'));
+  }
+
+  console.log(COLORS.cyan(`\n[STAT] ${safe.length} installed, ${blocked.length} skipped, ${excluded.length} excluded`));
+}
+
+async function checkPackages(packages, options) {
+  const config = mergeCliConfig(loadConfig(CWD), options);
+
+  let pkgsToCheck = packages;
+  let isPackageJson = false;
+
+  if (packages.length === 0) {
+    const pkgPath = path.join(CWD, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      console.error(COLORS.red('No package.json found'));
+      process.exit(1);
+    }
+
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = [
+        ...Object.keys(pkg.dependencies || {}),
+        ...Object.keys(pkg.devDependencies || {}),
+      ];
+
+      if (deps.length === 0) {
+        console.log(COLORS.yellow('No dependencies found in package.json'));
+        return;
+      }
+
+      pkgsToCheck = deps.map((dep) => {
+        const version = pkg.dependencies?.[dep] || pkg.devDependencies?.[dep] || '';
+        return version ? `${dep}@${version}` : dep;
+      });
+
+      isPackageJson = true;
+      console.log(COLORS.cyan(`\n📋 Checking ${pkgsToCheck.length} dependencies from package.json...\n`));
+    } catch {
+      console.error(COLORS.red('Error reading package.json'));
+      process.exit(1);
+    }
+  } else {
+    console.log(COLORS.cyan(`\n📋 Checking ${pkgsToCheck.length} package(s)...\n`));
+  }
+
+  const results = await validatePackages(pkgsToCheck, config, CWD);
+
+  const safe = results.filter((r) => r.allowed && r.reason !== 'excluded');
+  const blocked = results.filter((r) => !r.allowed);
+  const excluded = results.filter((r) => r.reason === 'excluded');
+
+  console.log(COLORS.green('✅ Safe to install (old enough):'));
+  if (safe.length === 0) {
+    console.log(COLORS.dim('   (none)'));
+  } else {
+    safe.forEach((r) => {
+      console.log(`   - ${r.fullSpec} (${formatAge(r.ageMinutes)} old)`);
+    });
+  }
+
+  console.log(COLORS.yellow('\n⚠️  Too new (would be blocked):'));
+  if (blocked.length === 0) {
+    console.log(COLORS.dim('   (none)'));
+  } else {
+    blocked.forEach((r) => {
+      console.log(`   - ${r.fullSpec} (${formatAge(r.ageMinutes)} old, min: ${config.minimumReleaseAge} min)`);
+    });
+  }
+
+  console.log(COLORS.cyan('\n⏭️  Excluded (no checks performed):'));
+  if (excluded.length === 0) {
+    console.log(COLORS.dim('   (none)'));
+  } else {
+    excluded.forEach((r) => {
+      console.log(`   - ${r.name}`);
+    });
+  }
+
+  console.log(COLORS.cyan(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`));
+  console.log(COLORS.cyan(`📊 Summary: ${safe.length} safe, ${blocked.length} blocked, ${excluded.length} excluded`));
+  console.log(COLORS.cyan(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`));
+
+  if (!isPackageJson) {
+    console.log(COLORS.dim('\nUse age-install install <packages> to install safe packages.'));
+  }
+
+  if (options.report) {
+    const reportFile = options.reportFile || generateReportFilename();
+    const reportData = generateReportData(config, safe, blocked, excluded, isPackageJson);
+
+    try {
+      fs.writeFileSync(reportFile, JSON.stringify(reportData, null, 2));
+      console.log(COLORS.green(`\n📄 Report saved to: ${reportFile}`));
+    } catch (err) {
+      console.error(COLORS.red(`\nFailed to save report: ${err.message}`));
+    }
+  }
+}
+
+function generateReportFilename() {
+  const now = new Date();
+  const date = now.toISOString().split('T')[0];
+  return `age-install-report-${date}.json`;
+}
+
+function generateReportData(config, safe, blocked, excluded, isPackageJson) {
+  return {
+    generated: new Date().toISOString(),
+    minimumAge: config.minimumReleaseAge,
+    source: isPackageJson ? 'package.json' : 'command-line',
+    summary: {
+      safe: safe.length,
+      blocked: blocked.length,
+      excluded: excluded.length,
+      total: safe.length + blocked.length + excluded.length,
+    },
+    safe: safe.map((r) => ({
+      name: r.name,
+      version: r.version,
+      fullSpec: r.fullSpec,
+      ageMinutes: Math.round(r.ageMinutes),
+      timestamp: r.timestamp,
+    })),
+    blocked: blocked.map((r) => ({
+      name: r.name,
+      version: r.version,
+      fullSpec: r.fullSpec,
+      ageMinutes: Math.round(r.ageMinutes),
+      ageFormatted: formatAge(r.ageMinutes),
+      timestamp: r.timestamp,
+    })),
+    excluded: excluded.map((r) => ({
+      name: r.name,
+    })),
+  };
+}
+
+function runNpm(args) {
+  try {
+    execSync(`npm ${args.join(' ')}`, { stdio: 'inherit' });
+  } catch (err) {
+    process.exit(err.status || 1);
+  }
+}
+
+function showHelp() {
+  console.log(`
+age-install - Delay npm package installations until they reach a minimum age
+
+Usage:
+  age-install [command] [options] [packages...]
+
+Commands:
+  install [packages]    Install packages with safety checks
+  add <packages>       Add packages to package.json with safety checks
+  check [packages]     Check packages without installing (generate report)
+  exec -- <cmd>        Run npm command (passthrough - no safety checks)
+  cache               Manage timestamp cache
+
+Options:
+  -m, --minimum-age <minutes>  Minimum age before installing (default: 60)
+  -e, --exclude <packages>       Packages to exclude from checks
+  -v, --verbose                Show detailed output
+  -f, --force                  Skip all safety checks
+  -r, --report                 Save report to JSON file
+  --report-file <path>          Custom report file path
+  -h, --help                   Show this help message
+  -V, --version                Show version
+
+Examples:
+  age-install install react lodash
+  age-install check react lodash      # Generate report without installing
+  age-install check                  # Check all deps in package.json
+  age-install check --report         # Save report to age-install-report-YYYY-MM-DD.json
+  age-install check --report --report-file ./my-report.json
+  age-install add typescript
+  age-install cache --clear
+`);
+}
+
+async function main() {
+  const parsed = parseArgs(ARGS);
+
+  if (parsed.options.help) {
+    showHelp();
+    return;
+  }
+
+  if (parsed.options.version) {
+    console.log('age-install v0.1.0');
+    return;
+  }
+
+  if (!parsed.command) {
+    if (parsed.packages.length === 0) {
+      console.log(COLORS.yellow('No packages specified. Checking package.json dependencies...'));
+      await installFromPackageJson(mergeCliConfig(loadConfig(CWD), parsed.options));
+      return;
+    }
+    parsed.command = 'install';
+  }
+
+  switch (parsed.command) {
+    case 'install':
+      if (parsed.packages.length === 0) {
+        console.log(COLORS.yellow('No packages specified. Checking package.json dependencies...'));
+        await installFromPackageJson(mergeCliConfig(loadConfig(CWD), parsed.options));
+      } else {
+        await installWithChecks(parsed.packages, parsed.options);
+      }
+      break;
+    case 'add':
+      await installWithChecks(parsed.packages, parsed.options, '--save');
+      break;
+    case 'check':
+      await checkPackages(parsed.packages, parsed.options);
+      break;
+    case 'exec':
+      runNpm(ARGS.slice(ARGS.indexOf('--') + 1));
+      break;
+    case 'cache':
+      handleCache(parsed.options);
+      break;
+  }
+}
+
+function handleCache(options) {
+  const cacheFile = path.join(CWD, 'node_modules', '.age-install-cache', 'timestamps.json');
+
+  if (options.clear) {
+    if (fs.existsSync(cacheFile)) {
+      fs.unlinkSync(cacheFile);
+      console.log(COLORS.green('Cache cleared successfully'));
+    } else {
+      console.log(COLORS.yellow('Cache is already empty'));
+    }
+    return;
+  }
+
+  if (fs.existsSync(cacheFile)) {
+    const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    console.log(COLORS.cyan(`\n[PKG] Cached packages: ${Object.keys(cache).length}`));
+    console.log(COLORS.dim('(Use age-install cache --clear to clear)'));
+  } else {
+    console.log(COLORS.yellow('No cache found'));
+  }
+}
+
+main().catch((err) => {
+  console.error(COLORS.red(`Error: ${err.message}`));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "age-install",
+  "version": "0.1.0",
+  "description": "Delay npm package installations until they reach a minimum age, protecting against supply chain attacks",
+  "bin": {
+    "age-install": "./bin/age-install.js"
+  },
+  "scripts": {
+    "start": "node bin/age-install.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "npm",
+    "security",
+    "supply-chain",
+    "delayed-dependencies",
+    "package-security",
+    "dependency-safety",
+    "malicious-packages",
+    "install-safe",
+    "ci-cd",
+    "audit"
+  ],
+  "author": "cinfinit",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/cinfinit/age-install/issues"
+  },
+  "homepage": "https://github.com/cinfinit/age-install#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cinfinit/age-install.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cache.js

@@ -0,0 +1,76 @@
+const fs = require('fs');
+const path = require('path');
+
+const CACHE_DIR = '.age-install-cache';
+const CACHE_FILE = 'timestamps.json';
+
+function getCacheDir(cwd = process.cwd()) {
+  return path.join(cwd, 'node_modules', CACHE_DIR);
+}
+
+function getCacheFilePath(cwd = process.cwd()) {
+  return path.join(getCacheDir(cwd), CACHE_FILE);
+}
+
+function loadCache(cwd = process.cwd()) {
+  const cachePath = getCacheFilePath(cwd);
+  if (!fs.existsSync(cachePath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveCache(cache, cwd = process.cwd()) {
+  const cacheDir = getCacheDir(cwd);
+  const cachePath = getCacheFilePath(cwd);
+
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+}
+
+function getFromCache(pkg, cwd = process.cwd()) {
+  const cache = loadCache(cwd);
+  return cache[pkg] || null;
+}
+
+function setInCache(pkg, timestamp, cwd = process.cwd()) {
+  const cache = loadCache(cwd);
+  cache[pkg] = timestamp;
+  saveCache(cache, cwd);
+}
+
+function getMultipleFromCache(packages, cwd = process.cwd()) {
+  const cache = loadCache(cwd);
+  const results = {};
+
+  for (const pkg of packages) {
+    results[pkg] = cache[pkg] || null;
+  }
+
+  return results;
+}
+
+function setMultipleInCache(entries, cwd = process.cwd()) {
+  const cache = loadCache(cwd);
+
+  for (const [pkg, timestamp] of Object.entries(entries)) {
+    cache[pkg] = timestamp;
+  }
+
+  saveCache(cache, cwd);
+}
+
+module.exports = {
+  getCacheDir,
+  getCacheFilePath,
+  loadCache,
+  saveCache,
+  getFromCache,
+  setInCache,
+  getMultipleFromCache,
+  setMultipleInCache,
+};

package/src/config.js

@@ -0,0 +1,78 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_MIN_AGE = 60;
+
+function loadConfig(cwd = process.cwd()) {
+  const config = {
+    minimumReleaseAge: DEFAULT_MIN_AGE,
+    minimumReleaseAgeExclude: [],
+    verbose: false,
+    force: false,
+  };
+
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.ageInstall) {
+        if (typeof pkg.ageInstall.minimumReleaseAge === 'number') {
+          config.minimumReleaseAge = pkg.ageInstall.minimumReleaseAge;
+        }
+        if (Array.isArray(pkg.ageInstall.minimumReleaseAgeExclude)) {
+          config.minimumReleaseAgeExclude = [...pkg.ageInstall.minimumReleaseAgeExclude];
+        }
+      }
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  const npmrcPath = path.join(cwd, '.npmrc');
+  if (fs.existsSync(npmrcPath)) {
+    const content = fs.readFileSync(npmrcPath, 'utf8');
+    const minAgeMatch = content.match(/age-install\.minimumReleaseAge=(\d+)/);
+    if (minAgeMatch) {
+      config.minimumReleaseAge = parseInt(minAgeMatch[1], 10);
+    }
+    const excludeMatch = content.match(/age-install\.minimumReleaseAgeExclude=(.+)/);
+    if (excludeMatch) {
+      config.minimumReleaseAgeExclude = excludeMatch[1].split(',').map((s) => s.trim());
+    }
+  }
+
+  if (process.env.AGE_INSTALL_MIN_AGE) {
+    config.minimumReleaseAge = parseInt(process.env.AGE_INSTALL_MIN_AGE, 10);
+  }
+  if (process.env.AGE_INSTALL_EXCLUDE) {
+    config.minimumReleaseAgeExclude = process.env.AGE_INSTALL_EXCLUDE.split(',').map((s) => s.trim());
+  }
+
+  return config;
+}
+
+function mergeCliConfig(config, cliOptions = {}) {
+  const merged = { ...config };
+
+  if (cliOptions.minimumAge !== undefined) {
+    merged.minimumReleaseAge = cliOptions.minimumAge;
+  }
+  if (cliOptions.exclude) {
+    const excludes = cliOptions.exclude.split(',').map((s) => s.trim());
+    merged.minimumReleaseAgeExclude = [...merged.minimumReleaseAgeExclude, ...excludes];
+  }
+  if (cliOptions.verbose) {
+    merged.verbose = true;
+  }
+  if (cliOptions.force) {
+    merged.force = true;
+  }
+
+  return merged;
+}
+
+module.exports = {
+  loadConfig,
+  mergeCliConfig,
+  DEFAULT_MIN_AGE,
+};

package/src/exclusion.js

@@ -0,0 +1,25 @@
+function isExcluded(packageName, exclusions) {
+  if (!exclusions || exclusions.length === 0) {
+    return false;
+  }
+
+  for (const pattern of exclusions) {
+    if (pattern.startsWith('^')) {
+      const regex = new RegExp(pattern.slice(1));
+      if (regex.test(packageName)) {
+        return true;
+      }
+    } else if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      if (regex.test(packageName)) {
+        return true;
+      }
+    } else if (packageName === pattern) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+module.exports = { isExcluded };

package/src/registry.js

@@ -0,0 +1,85 @@
+const { execSync } = require('child_process');
+
+const NPM_TIMEOUT = 15000;
+
+function execNpmView(args) {
+  return execSync(`npm view ${args.join(' ')}`, {
+    encoding: 'utf8',
+    timeout: NPM_TIMEOUT,
+  }).trim();
+}
+
+function parsePackageSpec(packageSpec) {
+  if (packageSpec.startsWith('@')) {
+    const atIndex = packageSpec.indexOf('@', 1);
+    if (atIndex === -1) {
+      return { name: packageSpec, version: null };
+    }
+    const name = packageSpec.slice(0, atIndex);
+    let version = packageSpec.slice(atIndex + 1);
+    if (version === '' || version === 'latest') {
+      version = null;
+    }
+    return { name, version };
+  }
+
+  const atIndex = packageSpec.indexOf('@');
+  if (atIndex === -1) {
+    return { name: packageSpec, version: null };
+  }
+
+  const name = packageSpec.slice(0, atIndex);
+  let version = packageSpec.slice(atIndex + 1);
+
+  if (version === '' || version === 'latest') {
+    version = null;
+  }
+
+  return { name, version };
+}
+
+function resolveVersion(packageSpec) {
+  const { name, version } = parsePackageSpec(packageSpec);
+
+  if (!version) {
+    return execNpmView([name, 'version']);
+  }
+
+  if (version.includes('*') || version.includes('^') || version.includes('~') || version.includes('>')) {
+    const result = execNpmView([`${name}@${version}`, 'version']);
+    return result.split('\n').pop().trim();
+  }
+
+  if (/^\d+$/.test(version)) {
+    return execNpmView([name, 'version']);
+  }
+
+  return version;
+}
+
+function getVersionTime(packageName, requestedVersion) {
+  const targetVersion = requestedVersion || execNpmView([packageName, 'version']);
+  const timeData = JSON.parse(execNpmView([packageName, 'time', '--json']));
+
+  if (timeData[targetVersion]) {
+    return { version: targetVersion, timestamp: timeData[targetVersion] };
+  }
+
+  const latestVersion = execNpmView([packageName, 'version']);
+  return {
+    version: latestVersion,
+    timestamp: timeData[latestVersion] || null,
+  };
+}
+
+function getPackageInfo(packageName) {
+  const output = execNpmView([packageName, '--json']);
+  return JSON.parse(output);
+}
+
+module.exports = {
+  parsePackageSpec,
+  resolveVersion,
+  getVersionTime,
+  getPackageInfo,
+};

package/src/validator.js

@@ -0,0 +1,102 @@
+const cache = require('./cache');
+const registry = require('./registry');
+const exclusion = require('./exclusion');
+
+function getAgeInMinutes(timestamp) {
+  if (!timestamp) {
+    return Infinity;
+  }
+  return (Date.now() - new Date(timestamp).getTime()) / 1000 / 60;
+}
+
+function isSafe(timestamp, minAge) {
+  return getAgeInMinutes(timestamp) >= minAge;
+}
+
+async function validatePackage(packageSpec, config, cwd) {
+  const { name, version: requestedVersion } = registry.parsePackageSpec(packageSpec);
+  const resolvedVersion = registry.resolveVersion(packageSpec);
+  const fullSpec = `${name}@${resolvedVersion}`;
+
+  if (exclusion.isExcluded(name, config.minimumReleaseAgeExclude)) {
+    if (config.verbose) {
+      console.log(`  [>>] ${name} - excluded from checks`);
+    }
+    return {
+      name,
+      version: resolvedVersion,
+      fullSpec,
+      allowed: true,
+      reason: 'excluded',
+      timestamp: null,
+      ageMinutes: 0,
+    };
+  }
+
+  const cached = cache.getFromCache(fullSpec, cwd);
+  let timestamp = cached;
+  let version = resolvedVersion;
+
+  if (!cached) {
+    if (config.verbose) {
+      console.log(`  [..] ${name} - querying registry...`);
+    }
+    const info = registry.getVersionTime(name, resolvedVersion);
+    timestamp = info.timestamp;
+    version = info.version;
+
+    if (timestamp) {
+      cache.setInCache(`${name}@${version}`, timestamp, cwd);
+    }
+  } else if (config.verbose) {
+    console.log(`  [OK] ${name} - cache hit`);
+  }
+
+  if (!timestamp) {
+    return {
+      name,
+      version,
+      fullSpec: `${name}@${version}`,
+      allowed: true,
+      reason: 'no_timestamp',
+      timestamp: null,
+      ageMinutes: Infinity,
+    };
+  }
+
+  const ageMinutes = getAgeInMinutes(timestamp);
+
+  if (config.verbose) {
+    const ageStr = ageMinutes > 60
+      ? `${(ageMinutes / 60).toFixed(1)} hours`
+      : `${Math.round(ageMinutes)} minutes`;
+    console.log(`  [AGE] ${name}@${version} - published ${ageStr} ago`);
+  }
+
+  const safe = isSafe(timestamp, config.minimumReleaseAge);
+
+  return {
+    name,
+    version,
+    fullSpec: `${name}@${version}`,
+    allowed: safe,
+    reason: safe ? 'age_ok' : 'too_new',
+    timestamp,
+    ageMinutes,
+  };
+}
+
+async function validatePackages(packages, config, cwd) {
+  const results = [];
+  for (const pkg of packages) {
+    results.push(await validatePackage(pkg, config, cwd));
+  }
+  return results;
+}
+
+module.exports = {
+  getAgeInMinutes,
+  isSafe,
+  validatePackage,
+  validatePackages,
+};