safeinstall-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_options_1 = require("./cli-options");
+const check_flow_1 = require("./check-flow");
+const init_flow_1 = require("./init-flow");
+const install_flow_1 = require("./install-flow");
+const output_1 = require("./output");
+const signals_1 = require("./signals");
+const PACKAGE_VERSION = String(require("../package.json").version ?? "0.0.0");
+function isHelpRequest(argv) {
+    return argv[0] === "--help" || argv[0] === "-h";
+}
+function isVersionRequest(argv) {
+    return argv[0] === "--version" || argv[0] === "-v";
+}
+function printHelp() {
+    process.stdout.write([
+        "Usage:",
+        "  safeinstall <npm|pnpm|bun> <install-command> [...args]",
+        "  safeinstall check",
+        "  safeinstall init [--force]",
+        "",
+        "Global options:",
+        "  --json       Emit machine-readable JSON output.",
+        "  --help, -h   Show this help text.",
+        "  --version, -v  Show the current SafeInstall version."
+    ].join("\n") + "\n");
+}
+async function main() {
+    const [, , ...rawArgv] = process.argv;
+    const { args: argv, json } = (0, cli_options_1.parseCliOptions)(rawArgv);
+    const shutdown = (0, signals_1.createShutdownController)();
+    try {
+        if (isHelpRequest(argv)) {
+            printHelp();
+            process.exitCode = 0;
+            return;
+        }
+        if (isVersionRequest(argv)) {
+            process.stdout.write(`${PACKAGE_VERSION}\n`);
+            process.exitCode = 0;
+            return;
+        }
+        let result;
+        if (argv[0] === "check") {
+            result = await (0, check_flow_1.runCheckFlow)(process.cwd(), argv, {
+                signal: shutdown.signal
+            });
+            (0, output_1.writeCliResult)(result, json);
+            process.exitCode = result.exitCode;
+            return;
+        }
+        if (argv[0] === "init") {
+            result = await (0, init_flow_1.runInitFlow)(process.cwd(), argv, {
+                force: argv.includes("--force")
+            });
+            (0, output_1.writeCliResult)(result, json);
+            process.exitCode = result.exitCode;
+            return;
+        }
+        result = await (0, install_flow_1.runInstallFlow)(process.cwd(), argv, {
+            jsonMode: json,
+            signal: shutdown.signal
+        });
+        (0, output_1.writeCliResult)(result, json);
+        process.exitCode = result.exitCode;
+    }
+    catch (error) {
+        const interrupted = error instanceof signals_1.ShutdownSignalError;
+        const result = {
+            mode: argv[0] === "check" ? "check" : argv[0] === "init" ? "init" : "install",
+            decision: "error",
+            exitCode: interrupted ? (0, signals_1.signalExitCode)(error.signalName) : 1,
+            exitCodeMeaning: interrupted
+                ? `SafeInstall was interrupted by ${error.signalName}.`
+                : "SafeInstall failed before it could complete the command.",
+            command: argv,
+            commandString: (0, output_1.formatCommand)("safeinstall", argv),
+            reasons: [
+                {
+                    code: interrupted ? "interrupted" : "runtime-error",
+                    message: error instanceof Error ? error.message : String(error)
+                }
+            ],
+            summary: interrupted ? "SafeInstall interrupted." : "SafeInstall failed.",
+            warnings: [],
+            affectedPackages: []
+        };
+        (0, output_1.writeCliResult)(result, json);
+        process.exitCode = result.exitCode;
+    }
+    finally {
+        shutdown.dispose();
+    }
+}
+void main();

package/dist/config.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REGISTRY_URL = exports.CONFIG_FILE_NAME = void 0;
+exports.createDefaultConfig = createDefaultConfig;
+exports.getConfigPath = getConfigPath;
+exports.serializeConfig = serializeConfig;
+exports.loadConfig = loadConfig;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const project_discovery_1 = require("./project-discovery");
+exports.CONFIG_FILE_NAME = "safeinstall.config.json";
+exports.DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+function normalizeRegistryUrl(input) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(input);
+    }
+    catch {
+        throw new Error("Config error: registryUrl must be a valid http or https URL.");
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new Error("Config error: registryUrl must use http or https.");
+    }
+    const normalizedPathname = parsedUrl.pathname.replace(/\/+$/, "");
+    parsedUrl.pathname = normalizedPathname === "" ? "/" : normalizedPathname;
+    return parsedUrl.toString().replace(/\/$/, "");
+}
+function createDefaultConfig() {
+    return {
+        minimumReleaseAgeHours: 72,
+        registryUrl: exports.DEFAULT_REGISTRY_URL,
+        allowedScripts: {},
+        allowedSources: ["registry", "workspace", "file", "directory"],
+        allowedPackages: [],
+        ciMode: process.env.CI === "true",
+        packageManagerDefaults: {
+            npm: { ignoreScripts: true },
+            pnpm: { ignoreScripts: true },
+            bun: { ignoreScripts: true }
+        }
+    };
+}
+function isPackageManagerName(value) {
+    return value === "npm" || value === "pnpm" || value === "bun";
+}
+function mergeConfig(input) {
+    const defaultConfig = createDefaultConfig();
+    const merged = {
+        ...defaultConfig,
+        ...input,
+        allowedScripts: {
+            ...defaultConfig.allowedScripts,
+            ...(input.allowedScripts ?? {})
+        },
+        packageManagerDefaults: {
+            npm: {
+                ...defaultConfig.packageManagerDefaults.npm,
+                ...(input.packageManagerDefaults?.npm ?? {})
+            },
+            pnpm: {
+                ...defaultConfig.packageManagerDefaults.pnpm,
+                ...(input.packageManagerDefaults?.pnpm ?? {})
+            },
+            bun: {
+                ...defaultConfig.packageManagerDefaults.bun,
+                ...(input.packageManagerDefaults?.bun ?? {})
+            }
+        }
+    };
+    if (!Number.isFinite(merged.minimumReleaseAgeHours) || merged.minimumReleaseAgeHours < 0) {
+        throw new Error("Config error: minimumReleaseAgeHours must be a non-negative number.");
+    }
+    merged.registryUrl = normalizeRegistryUrl(merged.registryUrl);
+    for (const source of merged.allowedSources) {
+        if (source !== "registry" &&
+            source !== "git" &&
+            source !== "tarball" &&
+            source !== "url" &&
+            source !== "file" &&
+            source !== "directory" &&
+            source !== "workspace" &&
+            source !== "unknown") {
+            throw new Error(`Config error: unsupported source type "${source}".`);
+        }
+    }
+    for (const [packageName, scripts] of Object.entries(merged.allowedScripts)) {
+        if (!Array.isArray(scripts)) {
+            throw new Error(`Config error: allowedScripts.${packageName} must be an array.`);
+        }
+        for (const script of scripts) {
+            if (script !== "preinstall" && script !== "install" && script !== "postinstall") {
+                throw new Error(`Config error: allowedScripts.${packageName} contains unsupported script "${script}".`);
+            }
+        }
+    }
+    for (const [manager, defaults] of Object.entries(merged.packageManagerDefaults)) {
+        if (!isPackageManagerName(manager)) {
+            throw new Error(`Config error: unsupported package manager "${manager}".`);
+        }
+        if (typeof defaults.ignoreScripts !== "boolean") {
+            throw new Error(`Config error: packageManagerDefaults.${manager}.ignoreScripts must be a boolean.`);
+        }
+    }
+    return merged;
+}
+async function findConfigFile(startDir) {
+    return (0, project_discovery_1.findNearestUpward)(node_path_1.default.resolve(startDir), exports.CONFIG_FILE_NAME);
+}
+function getConfigPath(cwd) {
+    return node_path_1.default.join(cwd, exports.CONFIG_FILE_NAME);
+}
+function serializeConfig(config) {
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+async function loadConfig(startDir) {
+    const configPath = await findConfigFile(startDir);
+    if (!configPath) {
+        return { config: createDefaultConfig() };
+    }
+    const rawText = await (0, promises_1.readFile)(configPath, "utf8");
+    const parsed = JSON.parse(rawText);
+    return {
+        config: mergeConfig(parsed),
+        path: configPath
+    };
+}

package/dist/disk-cache.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiskCache = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+function defaultCacheDir() {
+    if (process.env.SAFEINSTALL_CACHE_DIR) {
+        return process.env.SAFEINSTALL_CACHE_DIR;
+    }
+    if (process.env.XDG_CACHE_HOME) {
+        return node_path_1.default.join(process.env.XDG_CACHE_HOME, "safeinstall");
+    }
+    if (process.platform === "darwin") {
+        return node_path_1.default.join(node_os_1.default.homedir(), "Library", "Caches", "SafeInstall");
+    }
+    return node_path_1.default.join(node_os_1.default.homedir(), ".cache", "safeinstall");
+}
+function hashKey(key) {
+    return (0, node_crypto_1.createHash)("sha256").update(key).digest("hex");
+}
+class DiskCache {
+    cacheDir;
+    ttlMs;
+    constructor(options) {
+        this.cacheDir = options.cacheDir ?? defaultCacheDir();
+        this.ttlMs = options.ttlMs;
+    }
+    async getJson(namespace, key) {
+        try {
+            const raw = await (0, promises_1.readFile)(this.cacheFilePath(namespace, key), "utf8");
+            const entry = JSON.parse(raw);
+            if (typeof entry.cachedAt !== "number") {
+                return undefined;
+            }
+            if (Date.now() - entry.cachedAt > this.ttlMs) {
+                return undefined;
+            }
+            return entry.value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async setJson(namespace, key, value) {
+        try {
+            const namespaceDir = node_path_1.default.join(this.cacheDir, namespace);
+            await (0, promises_1.mkdir)(namespaceDir, { recursive: true });
+            const payload = {
+                cachedAt: Date.now(),
+                value
+            };
+            await (0, promises_1.writeFile)(this.cacheFilePath(namespace, key), `${JSON.stringify(payload)}\n`, "utf8");
+        }
+        catch {
+            // Cache failures must never block installs or checks.
+        }
+    }
+    cacheFilePath(namespace, key) {
+        return node_path_1.default.join(this.cacheDir, namespace, `${hashKey(key)}.json`);
+    }
+}
+exports.DiskCache = DiskCache;

package/dist/evaluations.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateRequestedPackages = evaluateRequestedPackages;
+const async_1 = require("./async");
+const project_state_1 = require("./project-state");
+const policy_1 = require("./policy");
+const REGISTRY_EVALUATION_CONCURRENCY = 8;
+async function evaluateRequestedPackages(projectDir, requestedPackages, registryClient, config) {
+    const now = new Date();
+    return (0, async_1.mapConcurrent)(requestedPackages, REGISTRY_EVALUATION_CONCURRENCY, async (requested) => {
+        const priorState = await (0, project_state_1.loadProjectDependencyState)(projectDir, requested.name);
+        const priorLifecycleScripts = priorState?.installedVersion && requested.sourceType === "registry"
+            ? await registryClient.getLifecycleScripts(requested.name, priorState.installedVersion)
+            : [];
+        const resolvedRegistryPackage = requested.sourceType === "registry"
+            ? await registryClient.resolvePackage(requested)
+            : undefined;
+        return (0, policy_1.evaluatePackage)({
+            config,
+            requested,
+            now,
+            priorState,
+            resolvedRegistryPackage,
+            priorLifecycleScripts
+        });
+    });
+}

package/dist/init-flow.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitFlow = runInitFlow;
+const promises_1 = require("node:fs/promises");
+const config_1 = require("./config");
+const output_1 = require("./output");
+const project_discovery_1 = require("./project-discovery");
+async function runInitFlow(cwd, argv, options) {
+    const configPath = (0, config_1.getConfigPath)(cwd);
+    const alreadyExists = await (0, project_discovery_1.fileExists)(configPath);
+    if (alreadyExists && !options.force) {
+        return {
+            mode: "init",
+            decision: "error",
+            exitCode: 1,
+            exitCodeMeaning: "SafeInstall could not create the config file.",
+            command: argv,
+            commandString: (0, output_1.formatCommand)("safeinstall", argv),
+            reasons: [
+                {
+                    code: "config-exists",
+                    message: `Config already exists at ${configPath}.`,
+                    suggestion: "Re-run with --force to overwrite it intentionally."
+                }
+            ],
+            summary: "Init failed: config already exists.",
+            warnings: [],
+            affectedPackages: [],
+            details: {
+                configPath,
+                overwritten: false
+            }
+        };
+    }
+    const config = (0, config_1.createDefaultConfig)();
+    await (0, promises_1.writeFile)(configPath, (0, config_1.serializeConfig)(config), "utf8");
+    return {
+        mode: "init",
+        decision: "allow",
+        exitCode: 0,
+        exitCodeMeaning: "Config created successfully.",
+        command: argv,
+        commandString: (0, output_1.formatCommand)("safeinstall", argv),
+        reasons: [],
+        summary: alreadyExists ? "Starter config overwritten." : "Starter config created.",
+        warnings: [
+            "Edit allowedScripts, allowedSources, or allowedPackages only when you intend to trust that exception."
+        ],
+        affectedPackages: [],
+        details: {
+            configPath,
+            overwritten: alreadyExists
+        }
+    };
+}

package/dist/install-flow.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInstallFlow = runInstallFlow;
+const config_1 = require("./config");
+const evaluations_1 = require("./evaluations");
+const output_1 = require("./output");
+const package_managers_1 = require("./package-managers");
+const project_state_1 = require("./project-state");
+const project_discovery_1 = require("./project-discovery");
+const project_installs_1 = require("./project-installs");
+const registry_1 = require("./registry");
+const signals_1 = require("./signals");
+const specs_1 = require("./specs");
+function configLabel(configPath) {
+    return configPath ?? "built-in defaults";
+}
+function createProjectIssueReason(message) {
+    if (message.includes("declares") && message.includes("as packageManager")) {
+        return {
+            code: "package-manager-mismatch",
+            message,
+            suggestion: "Run SafeInstall with the declared package manager or update package.json intentionally."
+        };
+    }
+    if (message.includes("required for safeinstall")) {
+        return {
+            code: "lockfile-required",
+            message,
+            suggestion: "Create or refresh the lockfile before retrying the project install."
+        };
+    }
+    if (message.includes("missing from pnpm-lock.yaml") || message.includes("missing from package-lock.json")) {
+        return {
+            code: "lockfile-missing-entry",
+            message,
+            suggestion: "Refresh the lockfile so it contains every direct dependency declared in package.json."
+        };
+    }
+    if (message.includes("specifier")) {
+        return {
+            code: "lockfile-specifier-mismatch",
+            message,
+            suggestion: "Regenerate the lockfile so package.json and the lockfile agree before installing."
+        };
+    }
+    return {
+        code: "project-install-blocked",
+        message,
+        suggestion: "Fix the lockfile inconsistency before retrying."
+    };
+}
+async function collectTargetPackages(packageDir, effectiveCwd, argv) {
+    const plan = (0, specs_1.buildInstallPlan)(argv);
+    if (!plan.projectInstall) {
+        return { issues: [], plan };
+    }
+    const lockfileResult = await (0, project_installs_1.loadProjectInstallTargetsForManager)(effectiveCwd, packageDir, plan.manager);
+    if (lockfileResult) {
+        if (lockfileResult.issues.length > 0) {
+            return {
+                issues: lockfileResult.issues.map(createProjectIssueReason),
+                plan
+            };
+        }
+        return {
+            issues: [],
+            plan: {
+                ...plan,
+                packages: lockfileResult.targets.map((target) => target.requested)
+            }
+        };
+    }
+    const manifestDependencies = await (0, project_state_1.loadManifestDependencies)(packageDir);
+    const packages = Object.entries(manifestDependencies).map(([name, spec]) => (0, specs_1.parseManifestDependency)(name, spec));
+    return {
+        issues: [],
+        plan: {
+            ...plan,
+            packages
+        }
+    };
+}
+function createAffectedPackage(evaluation) {
+    return {
+        name: evaluation.requested.name,
+        requested: evaluation.requested.raw,
+        sourceType: evaluation.requested.sourceType,
+        resolvedVersion: evaluation.resolvedRegistryPackage?.resolvedVersion,
+        reasons: evaluation.blockedReasons,
+        warnings: evaluation.warnings
+    };
+}
+async function runInstallFlow(cwd, argv, options) {
+    (0, signals_1.throwIfAborted)(options.signal);
+    const rawPlan = (0, specs_1.buildInstallPlan)(argv);
+    const invocation = await (0, project_discovery_1.resolveInvocationContext)(cwd, [...rawPlan.managerArgs, ...rawPlan.forwardedArgs]);
+    const { config, path } = await (0, config_1.loadConfig)(invocation.effectiveCwd);
+    const commandString = (0, output_1.formatCommand)("safeinstall", argv);
+    if ((0, project_discovery_1.hasAmbiguousWorkspaceFlags)(rawPlan.manager, [...rawPlan.managerArgs, ...rawPlan.forwardedArgs])) {
+        return {
+            mode: "install",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Install was blocked because the target workspace is ambiguous.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            packageManager: rawPlan.manager,
+            reasons: [
+                {
+                    code: "ambiguous-workspace-target",
+                    message: "Install blocked: workspace-targeting flags are ambiguous for SafeInstall in this command.",
+                    suggestion: "Run SafeInstall from the target package directory or use -C/--prefix to point at one package."
+                }
+            ],
+            summary: "Install blocked.",
+            warnings: [],
+            affectedPackages: [],
+            execution: {
+                ranPackageManager: false
+            }
+        };
+    }
+    if (!invocation.packageDir && rawPlan.projectInstall) {
+        return {
+            mode: "install",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Install was blocked because the current directory does not map to a package.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            packageManager: rawPlan.manager,
+            reasons: [
+                {
+                    code: "package-root-not-found",
+                    message: "Install blocked: the current directory does not map to a package.json-backed project.",
+                    suggestion: "Run SafeInstall from a package directory or use -C/--prefix to target one package."
+                }
+            ],
+            summary: "Install blocked.",
+            warnings: [],
+            affectedPackages: [],
+            execution: {
+                ranPackageManager: false
+            }
+        };
+    }
+    const { issues, plan } = await collectTargetPackages(invocation.packageDir ?? invocation.effectiveCwd, invocation.effectiveCwd, argv);
+    if (issues.length > 0) {
+        return {
+            mode: "install",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Install was blocked by policy before the package manager ran.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            packageManager: plan.manager,
+            reasons: issues,
+            summary: "Install blocked.",
+            warnings: [],
+            affectedPackages: [],
+            execution: {
+                ranPackageManager: false
+            }
+        };
+    }
+    if (plan.packages.length === 0) {
+        return {
+            mode: "install",
+            decision: "error",
+            exitCode: 1,
+            exitCodeMeaning: "SafeInstall could not determine what to install.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            packageManager: plan.manager,
+            reasons: [
+                {
+                    code: "nothing-to-install",
+                    message: "Nothing to install: no package arguments were provided and package.json has no dependencies."
+                }
+            ],
+            summary: "Install failed: no packages found.",
+            warnings: [],
+            affectedPackages: [],
+            execution: {
+                ranPackageManager: false
+            }
+        };
+    }
+    const registryClient = new registry_1.RegistryClient({
+        registryUrl: config.registryUrl,
+        signal: options.signal
+    });
+    const evaluations = await (0, evaluations_1.evaluateRequestedPackages)(invocation.packageDir ?? invocation.effectiveCwd, plan.packages, registryClient, config);
+    const blocked = evaluations.filter((evaluation) => evaluation.blockedReasons.length > 0);
+    const warnings = evaluations.flatMap((evaluation) => evaluation.warnings);
+    if (blocked.length > 0) {
+        return {
+            mode: "install",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Install was blocked by policy before the package manager ran.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            packageManager: plan.manager,
+            reasons: blocked.flatMap((evaluation) => evaluation.blockedReasons),
+            summary: "Install blocked.",
+            warnings,
+            affectedPackages: blocked.map(createAffectedPackage),
+            execution: {
+                ranPackageManager: false
+            }
+        };
+    }
+    if (!options.jsonMode) {
+        (0, output_1.printConfigInfo)(path);
+        (0, output_1.printWarnings)(evaluations);
+        console.error("Allowed: policy checks passed.");
+    }
+    (0, signals_1.throwIfAborted)(options.signal);
+    const execution = await (0, package_managers_1.runPackageManager)({
+        manager: plan.manager,
+        managerArgs: plan.managerArgs,
+        command: plan.command,
+        forwardedArgs: plan.forwardedArgs,
+        config,
+        cwd,
+        signal: options.signal,
+        stdio: options.jsonMode ? "pipe" : "inherit"
+    });
+    return {
+        mode: "install",
+        decision: "allow",
+        exitCode: execution.code,
+        exitCodeMeaning: execution.code === 0
+            ? "Policy checks passed and the package manager completed successfully."
+            : "Policy checks passed, but the underlying package manager exited non-zero.",
+        command: argv,
+        commandString,
+        configPath: path,
+        configLabel: configLabel(path),
+        packageManager: plan.manager,
+        reasons: [],
+        summary: execution.code === 0
+            ? "Allowed: policy checks passed."
+            : `Allowed by policy, but ${plan.manager} exited with code ${execution.code}.`,
+        warnings,
+        affectedPackages: plan.packages.map((requested) => ({
+            name: requested.name,
+            requested: requested.raw,
+            sourceType: requested.sourceType,
+            reasons: [],
+            warnings: []
+        })),
+        execution: {
+            ranPackageManager: true,
+            packageManagerExitCode: execution.code,
+            stdout: execution.stdout,
+            stderr: execution.stderr
+        },
+        details: {
+            suppressHumanOutput: !options.jsonMode
+        }
+    };
+}