@visulima/vis 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/commands/cache.d.ts

@@ -1,86 +0,0 @@
-import type { Command } from "@visulima/cerebro";
-/**
- * Shape returned by `collectCacheEntries`. Kept close to what `removeOldEntries`
- * uses internally so we can render the list identically.
- */
-interface CacheEntry {
-    hash: string;
-    mtimeMs: number;
-    path: string;
-    sizeBytes: number;
-}
-/**
- * Reads the cache directory and returns one entry per cached task hash.
- * Skips any file/directory starting with `.` (index files, temp dirs).
- * @param cacheDirectory Absolute path to the cache root directory.
- * @returns Array of cache entries sorted newest-first by modification time.
- * Returns an empty array when the directory does not exist or is empty.
- */
-declare const collectCacheEntries: (cacheDirectory: string) => Promise<CacheEntry[]>;
-/**
- * Formats the difference between `now` and `mtimeMs` as a short age string:
- * "3m", "2h", "4d". The caller passes a shared `now` so rows in the same
- * listing use a consistent baseline.
- * @param mtimeMs File modification time in milliseconds since epoch.
- * @param now Reference timestamp in milliseconds since epoch. Defaults to `Date.now()`.
- * @returns A compact age string such as `"5s"`, `"10m"`, `"2h"`, or `"3d"`.
- */
-declare const formatAge: (mtimeMs: number, now?: number) => string;
-/**
- * `list` subcommand — prints a table of cached task entries.
- * @param cacheDirectory Absolute path to the cache directory to enumerate.
- * @param format Output format: `"table"` for a human-readable table, `"json"` for machine-readable JSON.
- * @param logger Console instance used for non-prefixed table rows.
- * @returns Resolves when output has been written.
- */
-declare const runList: (cacheDirectory: string, format: string, logger: Console) => Promise<void>;
-/**
- * `clean` subcommand — removes the entire cache directory.
- *
- * Uses `Cache.clear()` when the directory is inside `workspaceRoot` so we
- * match the task runner's own cleanup semantics. For custom `--cache-dir`
- * paths that live outside the workspace we fall back to `rm -r`, but only
- * after prompting for confirmation: users pointing at a shared location
- * (e.g. `~/.cache/...`) shouldn't lose unrelated data without an opt-in.
- * The prompt is skipped in non-TTY / CI contexts and when `--force` is set.
- *
- * Refuses outright when `cacheDirectory` resolves to the workspace root.
- * @param cacheDirectory Absolute path to the cache directory to remove.
- * @param workspaceRoot Absolute path to the workspace root (used for containment checks and `Cache` construction).
- * @param options `dryRun` previews without deleting; `force` skips the out-of-workspace confirmation prompt.
- * @returns Resolves when the operation completes (or is skipped / aborted).
- */
-declare const runClean: (cacheDirectory: string, workspaceRoot: string, options: {
-    dryRun: boolean;
-    force: boolean;
-}) => Promise<void>;
-/**
- * `prune` subcommand — removes stale entries (age + size) without nuking
- * everything. Mirrors `Cache.removeOldEntries()` which the runner invokes
- * automatically on each run.
- *
- * Both `--max-age-days` and `--max-size` are validated up-front so
- * malformed values produce a friendly CLI error instead of a stack trace
- * from inside `Cache`. The before/after count is a best-effort estimate —
- * a concurrent `vis run` could skew it, but the cache state remains correct.
- * @param cacheDirectory Absolute path to the cache directory to prune.
- * @param workspaceRoot Absolute path to the workspace root (passed to the `Cache` constructor).
- * @param options `maxCacheAgeDays` evicts entries older than N days; `maxCacheSize` (e.g. `"500MB"`)
- * evicts oldest entries until the total size is under the limit.
- * @returns Resolves when pruning completes or is skipped.
- */
-declare const runPrune: (cacheDirectory: string, workspaceRoot: string, options: {
-    maxCacheAgeDays?: number;
-    maxCacheSize?: string;
-}) => Promise<void>;
-/**
- * `size` subcommand — prints the cache directory's on-disk footprint without
- * the per-entry table.
- * @param cacheDirectory Absolute path to the cache directory to measure.
- * @param format `"table"` for human-readable output, `"json"` for machine-readable JSON.
- * @returns Resolves when output has been written.
- */
-declare const runSize: (cacheDirectory: string, format: string) => Promise<void>;
-declare const cache: Command;
-export default cache;
-export { collectCacheEntries, formatAge, runClean, runList, runPrune, runSize };

package/dist/commands/check.d.ts

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

package/dist/commands/ci.d.ts

@@ -1,19 +0,0 @@
-import type { Command } from "@visulima/cerebro";
-/**
- * `vis ci` bundles the CI lifecycle in a single entry:
- *
- * 1. Install dependencies (respecting lockfile / frozen install).
- * 2. Enforce project constraints (implicit, via the `run` command).
- * 3. Determine affected projects since the base ref.
- * 4. Run the requested targets on affected projects only.
- *
- * Meant to be invoked as a single command at the top of a CI job:
- *
- *   vis ci lint test build
- *
- * Compared to wiring these up by hand, this skips reinstalling when
- * already installed, uses CI-safe defaults, and picks up the base ref
- * from common CI provider environment variables.
- */
-declare const ci: Command;
-export default ci;

package/dist/commands/clean.d.ts

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

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

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-/**
- * `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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-/**
- * 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

@@ -1,41 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,42 +0,0 @@
-/**
- * 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

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

package/dist/commands/devcontainer.d.ts

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

package/dist/commands/dlx.d.ts

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

package/dist/commands/docker.d.ts

@@ -1,22 +0,0 @@
-import type { Command } from "@visulima/cerebro";
-/**
- * `vis docker scaffold` / `vis docker prune` — scaffolding and pruning
- * helpers that mirror moon's `moon docker scaffold` and `moon docker prune`
- * commands. Used inside Dockerfiles to keep install layers cache-friendly.
- *
- * Typical Dockerfile usage:
- *
- * ```dockerfile
- * FROM node:22 AS deps
- * WORKDIR /app
- * COPY .vis/docker/workspace/ ./
- * RUN pnpm install --frozen-lockfile
- *
- * FROM deps AS build
- * COPY .vis/docker/sources/ ./
- * RUN pnpm --filter my-app build
- * RUN vis docker prune --context=.vis/docker
- * ```
- */
-declare const docker: Command;
-export default docker;

package/dist/commands/doctor.d.ts

@@ -1,15 +0,0 @@
-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

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

package/dist/commands/generate.d.ts

@@ -1,10 +0,0 @@
-/**
- * `vis generate <template>` — in-repo scaffolding command.
- *
- * Discovers templates from `.vis/templates/`, `.moon/templates/`, and
- * `vis.config.ts` `generator.templates`, then runs the selected
- * template through prompts → produce → write.
- */
-import type { Command } from "@visulima/cerebro";
-declare const generate: Command;
-export default generate;

package/dist/commands/graph.d.ts

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

package/dist/commands/hook/constants.d.ts

@@ -1,8 +0,0 @@
-declare const HOOKS: readonly ["pre-commit", "pre-merge-commit", "prepare-commit-msg", "commit-msg", "post-commit", "applypatch-msg", "pre-applypatch", "post-applypatch", "pre-rebase", "post-rewrite", "post-checkout", "post-merge", "pre-push", "pre-auto-gc"];
-declare const DEFAULT_HOOKS_DIRECTORY = ".vis-hooks";
-interface InstallResult {
-    isError: boolean;
-    message: string;
-}
-export type { InstallResult };
-export { DEFAULT_HOOKS_DIRECTORY, HOOKS };

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

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

package/dist/commands/hook/install.d.ts

@@ -1,7 +0,0 @@
-import type { InstallResult } from "./constants.d.ts";
-/**
- * Generates the shell script that dispatches to user-defined hooks.
- */
-declare const hookScript: (directory: string) => string;
-declare const installHooks: (directory?: string) => InstallResult;
-export { hookScript, installHooks };

package/dist/commands/hook/migrate.d.ts

@@ -1,27 +0,0 @@
-import type { PackageManagerType } from "../migrate/types.d.ts";
-import type { InstallResult } from "./constants.d.ts";
-/**
- * Detects which husky directory is in use, if any.
- */
-declare const detectHuskyDirectory: (root: string) => string | undefined;
-/**
- * Transforms a husky hook script for vis.
- * Removes the common.sh sourcing line since vis handles PATH setup in its dispatcher.
- */
-declare const transformHookScript: (content: string) => string;
-/**
- * Detects the package manager used in the project.
- */
-declare const detectPackageManager: (root: string) => PackageManagerType;
-/**
- * Cleans husky references from package.json scripts.
- */
-declare const cleanPackageJsonScripts: (root: string) => {
-    modified: boolean;
-    removedScriptReferences: string[];
-};
-/**
- * Migrates from husky to vis hooks.
- */
-declare const migrateFromHusky: (root: string, hooksDirectory: string, logger: Console) => InstallResult;
-export { cleanPackageJsonScripts, detectHuskyDirectory, detectPackageManager, migrateFromHusky, transformHookScript };

package/dist/commands/hook/uninstall.d.ts

@@ -1,3 +0,0 @@
-import type { InstallResult } from "./constants.d.ts";
-declare const uninstallHooks: (directory?: string) => InstallResult;
-export { uninstallHooks };