@visulima/vis 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/catalog.d.ts

@@ -1,28 +1,29 @@
+import type { AcceptedRisk, PackageReportData, SocketSecurityOptions } from "./socket-security.d.ts";
 type UpdateTarget = "latest" | "minor" | "patch";
-interface ParsedVersion {
-    major: number;
-    minor: number;
-    patch: number;
-    prerelease: string;
-}
 interface SecurityVulnerability {
+    /** Alternate identifiers (CVE-*, GHSA-*, etc.) from the OSV database. */
+    aliases?: string[];
     cvssScore?: number;
     fixedVersions: string[];
     id: string;
     severity: "CRITICAL" | "HIGH" | "LOW" | "MODERATE" | "UNKNOWN";
     summary: string;
 }
+type SocketReport = Pick<PackageReportData, "alerts" | "license" | "score">;
 interface OutdatedEntry {
+    acceptedRisk?: AcceptedRisk;
     catalogName: string;
     currentRange: string;
     newRange: string;
     packageName: string;
+    socketReport?: SocketReport;
     targetVersion: string;
     updateType: "major" | "minor" | "patch";
     vulnerabilities?: SecurityVulnerability[];
 }
 interface CatalogCheckOptions {
     exclude: string[];
+    ignore: string[];
     include: string[];
     includePrerelease: boolean;
     security?: boolean;
@@ -32,6 +33,12 @@ interface ReadCatalogOptions {
     dev?: boolean;
     prod?: boolean;
 }
+interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string;
+}
 declare const parseVersion: (input: string) => ParsedVersion | undefined;
 declare const extractPrefix: (range: string) => string;
 declare const getUpdateType: (current: ParsedVersion, target: ParsedVersion) => "major" | "minor" | "none" | "patch";
@@ -83,9 +90,10 @@ declare const fetchVulnerabilities: (packages: {
 declare const findTargetVersion: (versions: string[], latest: string, currentRange: string, target: UpdateTarget, includePrerelease: boolean) => string | undefined;
 interface CheckOutdatedResult {
     failed: string[];
+    ignored: string[];
     outdated: OutdatedEntry[];
 }
-declare const checkOutdated: (catalogs: Map<string, Map<string, string>>, options: CatalogCheckOptions, npmrcConfig?: NpmrcConfig, onProgress?: (current: number, total: number) => void) => Promise<CheckOutdatedResult>;
+declare const checkOutdated: (catalogs: Map<string, Map<string, string>>, options: CatalogCheckOptions, npmrcConfig?: NpmrcConfig, onProgress?: (current: number, total: number) => void, workspaceRoot?: string, socketOptions?: SocketSecurityOptions, acceptedRisks?: Record<string, AcceptedRisk>) => Promise<CheckOutdatedResult>;
 declare const createBackup: (workspaceRoot: string, packageManager?: string, updates?: OutdatedEntry[]) => string | undefined;
 declare const restoreFromBackup: (workspaceRoot: string, packageManager?: string) => boolean;
 declare const hasBackup: (workspaceRoot: string, packageManager?: string) => boolean;
@@ -106,5 +114,5 @@ interface ChangelogInfo {
     repoUrl?: string;
 }
 declare const fetchChangelogInfo: (packages: OutdatedEntry[], timeoutMs?: number) => Promise<ChangelogInfo[]>;
-export type { CatalogCheckOptions, CatalogProvider, ChangelogInfo, CheckOutdatedResult, NpmrcConfig, OutdatedEntry, OutputFormat, ParsedVersion, ReadCatalogOptions, SecurityVulnerability, UpdateTarget, };
+export type { CatalogCheckOptions, CatalogProvider, ChangelogInfo, CheckOutdatedResult, NpmrcConfig, OutdatedEntry, OutputFormat, ReadCatalogOptions, SecurityVulnerability, SocketReport, UpdateTarget, };
 export { applyCatalogUpdates, applyPackageJsonUpdates, checkOutdated, createBackup, detectJsonIndent, extractPrefix, fetchChangelogInfo, fetchPackageVersions, fetchVulnerabilities, findTargetVersion, formatOutdatedJson, formatOutdatedMinimal, formatOutdatedTable, formatSummary, getRegistryForPackage, getUpdateType, groupByCatalog, hasBackup, hasCatalogs, hasPackageJsonDeps, isNewer, loadNpmrc, matchesFilters, matchesPattern, parseBunCatalogs, parseCatalogsFromYaml, parseCompositeCatalogName, parseNpmrc, parseVersion, promptPackageSelection, readCatalogs, readPackageJsonDeps, restoreFromBackup, toFilterArray, };

package/dist/commands/add.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const add: Command;
+export default add;

package/dist/commands/approve-builds.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const approveBuilds: Command;
+export default approveBuilds;

package/dist/commands/audit.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from "@visulima/cerebro";
+interface InstalledPackage {
+    isDev: boolean;
+    name: string;
+    version: string;
+}
+/** A package installed in multiple versions. */
+interface DuplicatePackage {
+    /** The package name. */
+    name: string;
+    /** Each installed version. */
+    versions: string[];
+}
+declare const scanInstalledPackages: (workspaceRoot: string) => InstalledPackage[];
+/**
+ * Finds packages with multiple installed versions by parsing the lockfile
+ * via `lockparse`. Passes `package.json` for accuracy (especially yarn).
+ */
+declare const findDuplicateDependencies: (workspaceRoot: string, pmName: string) => Promise<DuplicatePackage[]>;
+declare const audit: Command;
+export default audit;
+export type { DuplicatePackage, InstalledPackage };
+export { findDuplicateDependencies, scanInstalledPackages };

package/dist/commands/clean.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const clean: Command;
+export default clean;

package/dist/commands/create/discovery.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Template discovery — identifies and resolves template sources from user input.
+ *
+ * Supports:
+ * - Built-in templates prefixed with `vis:` (app, library, monorepo, generator)
+ * - npm `create-*` packages (with shorthand expansion)
+ * - Git repositories from GitHub, GitLab, Bitbucket, and Sourcehut (all URL formats)
+ * - Direct tarball/registry URLs via giget's http/https providers
+ */
+import type { TemplateConfig, TemplateType } from "./templates/types.d.ts";
+/**
+ * Check if the input looks like a git/tarball URL that giget can handle.
+ * @param input Raw user input string.
+ * @returns `true` when the input matches a known git host, provider prefix, or URL scheme.
+ */
+export declare const isGitUrl: (input: string) => boolean;
+/**
+ * Expand shorthand npm create names following the `npm create` convention:
+ *
+ * - `vite`       → `create-vite`
+ * - `@scope/foo` → `@scope/create-foo`
+ * - `create-vue` → `create-vue` (already expanded)
+ * - `sv`         → `sv` (direct-package initialiser, not expanded)
+ * @param name Bare package name or scoped package name.
+ * @returns Expanded package name suitable for `dlx`.
+ */
+export declare const expandCreateShorthand: (name: string) => string;
+/**
+ * Given the raw template string from the user, determine what kind of
+ * template it is and return a resolved {@link TemplateConfig}.
+ * @param input Raw template string (e.g., "vis:app", "vite", "user/repo").
+ * @param extraArgs Additional CLI arguments to forward to the template runner.
+ * @returns Resolved template configuration with type, source, and args.
+ */
+export declare const discoverTemplate: (input: string, extraArgs?: string[]) => TemplateConfig;
+/**
+ * Suggest the most appropriate parent directory for a new project based on
+ * the template type.
+ * @param type The resolved template type.
+ * @returns Suggested parent directory name ("apps", "packages", or ".").
+ */
+export declare const inferParentDir: (type: TemplateType) => string;

package/dist/commands/create/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `vis create` — full-featured project scaffolding command.
+ *
+ * Supports built-in templates (monorepo, app, library, generator),
+ * remote npm create-* packages, and git repository templates
+ * (GitHub, GitLab, Bitbucket, Sourcehut) via giget.
+ *
+ * Interactive mode guides users through template selection, naming,
+ * directory choice, and post-creation setup.
+ */
+import type { Command } from "@visulima/cerebro";
+declare const create: Command;
+export default create;

package/dist/commands/create/prompts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Interactive prompts for `vis create`.
+ *
+ * Uses `node:readline` (same pattern as `vis init`) to keep dependencies minimal.
+ */
+export interface PromptResult {
+    editor?: "vscode" | undefined;
+    gitInit: boolean;
+    /** Whether the user confirmed overwriting an existing non-empty directory. */
+    overwrite: boolean;
+    pm?: "bun" | "npm" | "pnpm" | "yarn" | undefined;
+    projectName: string;
+    targetDir: string;
+    template: string;
+}
+/**
+ * Run the full interactive prompt flow and return the collected answers.
+ * @param options.cwd Working directory for resolving paths.
+ * @param options.defaultPm Pre-selected package manager (skips PM prompt when set).
+ * @param options.defaultGitInit Default for the git-init prompt (from vis.config.ts).
+ * @param options.defaultEditor Default for the editor prompt (from vis.config.ts).
+ * @param options.inMonorepo Whether we are inside an existing monorepo workspace.
+ * @returns Collected answers including template, name, directory, PM, and flags.
+ */
+export declare const runInteractivePrompts: (options: {
+    cwd: string;
+    defaultEditor?: "vscode";
+    defaultGitInit?: boolean;
+    defaultPm?: string;
+    inMonorepo: boolean;
+}) => Promise<PromptResult>;

package/dist/commands/create/random-name.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Random project name generator — produces friendly `word-word` names
+ * used as default project name suggestions in interactive mode.
+ *
+ * Uses @nkzw/safe-word-list for a curated set of ~2700 safe English words.
+ */
+/**
+ * Generate a random `word-word` project name from the safe word list.
+ * @example
+ * ```ts
+ * randomName(); // "swift-ember"
+ * randomName(); // "bold-prism"
+ * ```
+ */
+export declare const randomName: () => string;

package/dist/commands/create/templates/builtin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Built-in template executor — routes `vis:app` and `vis:library`
+ * to appropriate scaffolding strategies.
+ *
+ * - `vis:app` delegates to `create-vite` via dlx
+ * - `vis:library` scaffolds a minimal TypeScript library package
+ */
+import type { ExecutionContext, TemplateConfig } from "./types.d.ts";
+/**
+ * Execute a built-in template (vis:app or vis:library).
+ * @param config Resolved template config with type and extra args.
+ * @param context Runtime context with PM info, target dir, and project name.
+ * @returns Exit code — 0 on success, non-zero on failure.
+ */
+export declare const executeBuiltin: (config: TemplateConfig, context: ExecutionContext) => number;

package/dist/commands/create/templates/generator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in generator template — scaffolds a code generator package
+ * inside an existing monorepo workspace.
+ *
+ * Creates a minimal Node.js CLI package with a bin entry point.
+ */
+import type { ExecutionContext } from "./types.d.ts";
+/**
+ * Scaffold a code generator package with a bin entry point.
+ * @param context Runtime context with project name and target directory.
+ * @param description Optional generator description for package.json.
+ * @returns Exit code — 0 on success.
+ */
+export declare const executeGeneratorTemplate: (context: ExecutionContext, description?: string) => number;

package/dist/commands/create/templates/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Template executor router — dispatches to the correct executor
+ * based on the resolved template type.
+ */
+import type { ExecutionContext, TemplateConfig } from "./types.d.ts";
+/**
+ * Execute a template given its resolved configuration and runtime context.
+ * @param config Resolved template info (type, source, extra args).
+ * @param context Runtime context (cwd, PM, project name, target dir, config).
+ * @returns Exit code — 0 on success, non-zero on failure.
+ */
+export declare const executeTemplate: (config: TemplateConfig, context: ExecutionContext) => Promise<number>;
+export type { ExecutionContext, TemplateConfig } from "./types.d.ts";

package/dist/commands/create/templates/monorepo.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Built-in monorepo template — scaffolds a complete pnpm workspace.
+ *
+ * Creates:
+ * - Root package.json with workspace scripts
+ * - pnpm-workspace.yaml
+ * - .gitignore, .editorconfig
+ * - apps/ and packages/ directories
+ */
+import type { ExecutionContext } from "./types.d.ts";
+/**
+ * Scaffold a pnpm monorepo workspace with apps/ and packages/ directories.
+ * @param context Execution context with project name, target directory, and PM info.
+ * @returns Exit code (0 = success).
+ */
+export declare const executeMonorepoTemplate: (context: ExecutionContext) => number;

package/dist/commands/create/templates/remote.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Remote template executors:
+ *
+ * - `executeRemoteNpm` — runs npm `create-*` packages via `dlx`
+ * - `executeRemoteGit` — downloads git repositories using giget
+ *   (GitHub, GitLab, Bitbucket, Sourcehut — tarballs with caching)
+ *
+ * Includes auto-fix rules for popular tools that need extra flags
+ * to play nicely with monorepo setups.
+ */
+import type { ExecutionContext, TemplateConfig } from "./types.d.ts";
+/**
+ * Execute an npm `create-*` package via the package manager's `dlx` command.
+ *
+ * Injects the target directory as the first positional argument if not
+ * already present, since most `create-*` packages expect the output
+ * directory as the first arg (e.g., `create-vite my-app`).
+ *
+ * Auto-fix rules are applied for known tools that need extra flags.
+ * @param config Resolved template config with source package name and extra args.
+ * @param context Runtime context with PM, cwd, target dir, and monorepo flag.
+ * @returns Exit code — 0 on success, non-zero on failure.
+ */
+export declare const executeRemoteNpm: (config: TemplateConfig, context: ExecutionContext) => number;
+/**
+ * Download a git repository template using giget.
+ *
+ * Supports GitHub, GitLab, Bitbucket, and Sourcehut — with tarball
+ * downloads, disk caching, offline support, subdirectory extraction,
+ * and private repo auth via tokens.
+ *
+ * Source format follows giget conventions:
+ * - `provider:owner/repo[/subpath][#ref]`
+ * - `owner/repo` (defaults to GitHub)
+ * - Full HTTPS URLs
+ * - `git:` prefix for raw git clone
+ * @param config Resolved template config with giget source string and extra args.
+ * @param context Runtime context with target dir and createConfig (auth, registry, etc.).
+ * @returns Exit code — 0 on success, 1 on failure.
+ */
+export declare const executeRemoteGit: (config: TemplateConfig, context: ExecutionContext) => Promise<number>;

package/dist/commands/create/templates/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Core type definitions for the `vis create` scaffolding system.
+ */
+/** The kind of template being scaffolded. */
+export type TemplateType = "builtin:app" | "builtin:generator" | "builtin:library" | "builtin:monorepo" | "remote:git" | "remote:npm";
+/** Resolved information about a template after discovery. */
+export interface TemplateConfig {
+    /** Extra CLI arguments forwarded to the template runner. */
+    args: string[];
+    /** The npm package name (for remote:npm) or git URL (for remote:git). */
+    source: string;
+    /** What kind of template this is. */
+    type: TemplateType;
+}
+/** Create config from vis.config.ts — full shape matching VisConfig.create. */
+export interface CreateConfig {
+    auth?: string;
+    defaultEditor?: "vscode";
+    defaultPm?: "bun" | "npm" | "pnpm" | "yarn";
+    defaultProvider?: "bitbucket" | "github" | "gitlab" | "sourcehut";
+    gitInit?: boolean;
+    install?: boolean;
+    preferOffline?: boolean;
+    registry?: false | string;
+    templates?: Record<string, string>;
+}
+/** Runtime context passed to every template executor. */
+export interface ExecutionContext {
+    /** Create config from vis.config.ts. */
+    createConfig?: CreateConfig;
+    /** Working directory (workspace root or cwd). */
+    cwd: string;
+    /** Whether we are inside an existing monorepo workspace. */
+    inMonorepo: boolean;
+    /** Console-compatible logger from Cerebro toolbox. */
+    logger: Console;
+    /** Detected package manager. */
+    pm: {
+        name: "bun" | "npm" | "pnpm" | "yarn";
+        version: string;
+    };
+    /** The validated npm-safe project name. */
+    projectName: string;
+    /** Absolute path to the target directory. */
+    targetDir: string;
+}

package/dist/commands/create/utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Utility helpers for the `vis create` command.
+ *
+ * - Package name validation & sanitisation
+ * - Directory emptiness / conflict checks
+ * - Target directory resolution
+ */
+/**
+ * Validate an npm package name using the official `validate-npm-package-name` library.
+ * Handles blacklisted names, core module conflicts, length limits, etc.
+ * @param name Package name to validate.
+ * @returns `true` when `name` is valid for new npm packages.
+ */
+export declare const isValidPackageName: (name: string) => boolean;
+/**
+ * Sanitise an arbitrary string into a valid npm package name.
+ * @param raw Arbitrary string to sanitise.
+ * @returns Lowercased, hyphen-separated name with special chars stripped.
+ */
+export declare const toValidPackageName: (raw: string) => string;
+/**
+ * Check if a directory is empty or contains only ignored files (.DS_Store, .git, etc.).
+ * @param dir Absolute path to check.
+ * @returns `true` when `dir` does not exist or contains only ignored files.
+ */
+export declare const isEmptyDir: (dir: string) => boolean;
+/**
+ * Resolve `projectName` relative to `cwd` into an absolute target directory path.
+ * @param projectName Project name or relative path.
+ * @param cwd Base directory to resolve from.
+ * @returns Object with absolute `targetDir` and sanitised `packageName`.
+ */
+export declare const resolveTargetDir: (projectName: string, cwd: string) => {
+    packageName: string;
+    targetDir: string;
+};
+/**
+ * Check whether scaffolding can proceed without overwriting user files.
+ * @param dir Absolute path to the target directory.
+ * @returns `true` when the directory is safe to write into (empty or non-existent).
+ */
+export declare const canSafelyOverwrite: (dir: string) => boolean;

package/dist/commands/dedupe.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const dedupe: Command;
+export default dedupe;

package/dist/commands/devcontainer.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const devcontainer: Command;
+export default devcontainer;

package/dist/commands/dlx.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const dlx: Command;
+export default dlx;

package/dist/commands/doctor.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from "@visulima/cerebro";
+/**
+ * `vis doctor` — unified project health check.
+ *
+ * Runs all diagnostic scans in parallel (outdated, vulnerabilities,
+ * Socket.dev scores, duplicates, optimization opportunities) and
+ * displays a single dashboard with actionable next steps.
+ * @example
+ * ```sh
+ * vis doctor           # full health check
+ * vis doctor --json    # machine-readable output
+ * ```
+ */
+declare const doctor: Command;
+export default doctor;

package/dist/commands/exec.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const exec: Command;
+export default exec;

package/dist/commands/implode.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const implode: Command;
+export default implode;

package/dist/commands/init.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "@visulima/cerebro";
+/**
+ * `vis init` — initialize vis configuration with secure defaults.
+ *
+ * In interactive mode (`--interactive` or TTY default), guides the user through:
+ * 1. Socket.dev security scanning (opt-in)
+ * 2. Build script approval (scans node_modules)
+ * 3. Git hooks / lint-staged setup
+ * 4. Native PM config sync
+ *
+ * In non-interactive mode (CI, piped), creates a minimal config with secure defaults.
+ */
+declare const init: Command;
+export default init;

package/dist/commands/install.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const install: Command;
+export default install;

package/dist/commands/link.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const link: Command;
+export default link;

package/dist/commands/optimize.d.ts

@@ -0,0 +1,38 @@
+import type { Command } from "@visulima/cerebro";
+import type { PmInfo } from "../overrides.d.ts";
+import type { OptimizeEntry } from "../tui/components/optimize/OptimizeStore.d.ts";
+/** Collects dependency names from a `package.json`. */
+declare const collectDepsFromPkgJson: (pkgJsonPath: string, productionOnly: boolean) => Set<string>;
+/** Discovers workspace package directories. */
+declare const discoverWorkspacePackages: (workspaceRoot: string) => string[];
+/** Scans deps against e18e module-replacements manifests. */
+declare const buildE18eEntries: (allDeps: Set<string>) => OptimizeEntry[];
+/** Scans deps against @socketregistry manifest. */
+declare const buildSocketEntries: (allDeps: Set<string>, lockText: string, pm: PmInfo, pin: boolean) => OptimizeEntry[];
+/** Marks e18e entries that have codemods available. */
+declare const markCodemodAvailability: (entries: OptimizeEntry[]) => Promise<void>;
+interface CodemodResult {
+    filesChanged: number;
+    packageName: string;
+}
+/**
+ * Runs a codemod for a single package across all source files in the project.
+ * Returns the number of files modified.
+ */
+declare const runCodemod: (workspaceRoot: string, packageName: string) => Promise<CodemodResult>;
+/**
+ * `vis optimize` — two-phase dependency optimization with interactive TUI.
+ *
+ * **Phase 1 (e18e):** Identifies packages replaceable with native builtins or lighter
+ * alternatives using `module-replacements` manifests. Runs source code codemods via
+ * `module-replacements-codemods` for selected entries.
+ *
+ * **Phase 2 (Socket.dev):** Writes override/resolution entries for packages that have
+ * security-hardened `@socketregistry` alternatives.
+ *
+ * In TTY mode, presents an interactive TUI (like `vis update`) where users select
+ * which optimizations to apply. In non-TTY/CI mode, outputs a static report.
+ */
+declare const optimize: Command;
+export default optimize;
+export { buildE18eEntries, buildSocketEntries, collectDepsFromPkgJson, discoverWorkspacePackages, markCodemodAvailability, runCodemod };

package/dist/commands/pm.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const pm: Command;
+export default pm;

package/dist/commands/remove.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const remove: Command;
+export default remove;

package/dist/commands/sort-package-json.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const sortPackageJson: Command;
+export default sortPackageJson;

package/dist/commands/unlink.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const unlink: Command;
+export default unlink;

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const upgrade: Command;
+export default upgrade;

package/dist/commands/why.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "@visulima/cerebro";
+declare const why: Command;
+export default why;

package/dist/config.d.ts

@@ -1,6 +1,19 @@
 import type { VisConfig } from "./workspace.d.ts";
 /** Supported config file names, checked in order. */
 declare const CONFIG_FILES: string[];
+/**
+ * Secure-by-default security settings based on npm supply chain best practices.
+ *
+ * These defaults are applied automatically when using `defineConfig()` or `loadVisConfig()`.
+ * Users can override any value — their settings always take precedence.
+ * @see https://github.com/lirantal/awesome-npm-security-best-practices
+ */
+declare const SECURITY_DEFAULTS: Required<Pick<NonNullable<VisConfig["security"]>, "blockExoticSubdeps" | "minimumReleaseAge" | "strictDepBuilds" | "trustPolicy" | "trustPolicyIgnoreAfter">>;
+/**
+ * Apply secure defaults to a raw config object.
+ * Merges `SECURITY_DEFAULTS` into `config.security`, preserving all user overrides.
+ */
+declare const applyDefaults: (config: VisConfig) => VisConfig;
 /**
  * Find the vis config file in a directory.
  * @param directory The directory to search in.
@@ -10,31 +23,45 @@ declare const findVisConfigFile: (directory: string) => string | undefined;
 /**
  * Load the vis configuration from a `vis.config.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`, `.cts`) file.
  *
- * Uses jiti for runtime TypeScript support — no build step needed for config files.
- * Falls back to an empty config if no config file is found.
+ * Uses a file-hash based cache to avoid repeated jiti compilations.
+ * Falls back to secure defaults if no config file is found.
  * @param workspaceRoot The workspace root directory to search for the config file.
- * @returns The loaded and resolved configuration.
+ * @returns The loaded and resolved configuration with secure defaults applied.
  */
 declare const loadVisConfig: (workspaceRoot: string) => Promise<VisConfig>;
 /**
  * Type-safe helper for defining vis configuration.
  * Provides full TypeScript autocomplete when used in `vis.config.ts`.
+ *
+ * Secure defaults are applied automatically — you only need to specify overrides.
+ * To see the active defaults, run `vis check --security-config`.
  * @example
  * ```typescript
- * // vis.config.ts
+ * // vis.config.ts — minimal config, fully secured by defaults
  * import { defineConfig } from "@visulima/vis/config";
  *
  * export default defineConfig({
- *     update: {
- *         target: "minor",
- *         exclude: ["@types/*"],
- *         security: true,
+ *     security: {
+ *         allowBuilds: {
+ *             esbuild: true,
+ *             "@prisma/client": true,
+ *         },
  *     },
- *     ai: {
- *         provider: "claude",
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // vis.config.ts — override a default
+ * import { defineConfig } from "@visulima/vis/config";
+ *
+ * export default defineConfig({
+ *     security: {
+ *         // Relax cooldown to 24 hours instead of the default 14 days
+ *         minimumReleaseAge: 1440,
+ *         allowBuilds: { esbuild: true },
  *     },
  * });
  * ```
  */
 declare const defineConfig: (config: VisConfig) => VisConfig;
-export { CONFIG_FILES, defineConfig, findVisConfigFile, loadVisConfig };
+export { applyDefaults, CONFIG_FILES, defineConfig, findVisConfigFile, loadVisConfig, SECURITY_DEFAULTS };

package/dist/config.js

@@ -1 +1 @@
-var r=Object.defineProperty;var n=(e,i)=>r(e,"name",{value:i,configurable:!0});import{createRequire as f}from"node:module";import{join as g}from"@visulima/path";import{createJiti as d}from"jiti";const c=f(import.meta.url),s=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,a=n(e=>{if(typeof s<"u"&&s.versions&&s.versions.node){const[i,o]=s.versions.node.split(".").map(Number);if(i>22||i===22&&o>=3||i===20&&o>=16)return s.getBuiltinModule(e)}return c(e)},"__cjs_getBuiltinModule"),{existsSync:u}=a("node:fs");var l=Object.defineProperty,t=n((e,i)=>l(e,"name",{value:i,configurable:!0}),"o");const m=["vis.config.ts","vis.config.mts","vis.config.cts","vis.config.js","vis.config.mjs","vis.config.cjs"],p=t(e=>{for(const i of m){const o=g(e,i);if(u(o))return o}},"findVisConfigFile"),C=t(async e=>{const i=p(e);if(!i)return{};const o=await d(e).import(i,{default:!0,try:!0})??{};return typeof o=="function"?await o():o},"loadVisConfig"),b=t(e=>e,"defineConfig");export{m as CONFIG_FILES,b as defineConfig,p as findVisConfigFile,C as loadVisConfig};
+var h=Object.defineProperty;var u=(e,t)=>h(e,"name",{value:t,configurable:!0});import{createRequire as C}from"node:module";import{findCacheDirSync as w}from"@visulima/find-cache-dir";import{ensureDirSync as p,isAccessibleSync as D,readJsonSync as I,writeJsonSync as x}from"@visulima/fs";import{join as o,dirname as E}from"@visulima/path";import{createJiti as P}from"jiti";const v=C(import.meta.url),r=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,d=u(e=>{if(typeof r<"u"&&r.versions&&r.versions.node){const[t,s]=r.versions.node.split(".").map(Number);if(t>22||t===22&&s>=3||t===20&&s>=16)return r.getBuiltinModule(e)}return v(e)},"__cjs_getBuiltinModule"),{createHash:_}=d("node:crypto"),{existsSync:y,readFileSync:S,copyFileSync:j,unlinkSync:b}=d("node:fs"),{tmpdir:F}=d("node:os");var T=Object.defineProperty,i=u((e,t)=>T(e,"name",{value:t,configurable:!0}),"e");const A=["vis.config.ts","vis.config.mts","vis.config.cts","vis.config.js","vis.config.mjs","vis.config.cjs"],J={blockExoticSubdeps:!0,minimumReleaseAge:20160,strictDepBuilds:!0,trustPolicy:"no-downgrade",trustPolicyIgnoreAfter:43200},R=i(e=>({...J,...e}),"mergeSecurityDefaults"),l=i(e=>({...e,security:R(e.security),update:{security:!0,target:"minor",...e.update}}),"applyDefaults"),V=i(e=>{for(const t of A){const s=o(e,t);if(y(s))return s}},"findVisConfigFile"),k=i(e=>_("sha256").update(S(e)).digest("hex"),"hashFileContents"),q=i(e=>{const t=o(e,"node_modules");if(y(t)){const n=o(t,".cache","vis");return p(n),o(n,"vis-config-cache.json")}const s=w("vis",{create:!0,cwd:e});return s?o(s,"vis-config-cache.json"):void 0},"getConfigCachePath"),B=i((e,t)=>{if(D(e))try{const s=I(e);if(s.hash===t)return s.config}catch{}},"readConfigCache"),N=i((e,t,s)=>{try{p(E(e)),x(e,{config:s,hash:t})}catch{}},"writeConfigCache"),H=i(async e=>{const t=V(e);if(!t)return l({});const s=k(t),n=q(e);if(n){const g=B(n,s);if(g)return g}const m=t.slice(t.lastIndexOf(".")),a=o(F(),`vis-config-${s}${m}`);j(t,a);let c;try{c=await P(e,{fsCache:!1,moduleCache:!1}).import(a,{default:!0,try:!0})??{}}finally{try{b(a)}catch{}}let f;return f=l(typeof c=="function"?await c()??{}:c),n&&N(n,s,f),f},"loadVisConfig"),Y=i(e=>l(e),"defineConfig");export{A as CONFIG_FILES,J as SECURITY_DEFAULTS,l as applyDefaults,Y as defineConfig,V as findVisConfigFile,H as loadVisConfig};