@visulima/vis 0.0.1 → 1.0.0-alpha.10

package/README.md

@@ -1,45 +1,380 @@
-# @visulima/vis
+<!-- START_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+<a href="https://www.anolilab.com/open-source" align="center">
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+  <img src="__assets__/package-og.svg" alt="vis" />
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+</a>
 
-## Purpose
+<h3 align="center">A CLI task runner for monorepo workspaces, powered by @visulima/task-runner</h3>
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@visulima/vis`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+<!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## What is OIDC Trusted Publishing?
+<br />
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+<div align="center">
 
-## Setup Instructions
+[![typescript-image][typescript-badge]][typescript-url]
+[![mit licence][license-badge]][license]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![Chat][chat-badge]][chat]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
-To properly configure OIDC trusted publishing for this package:
+</div>
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+---
 
-## DO NOT USE THIS PACKAGE
+<div align="center">
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
+</div>
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+---
 
-## More Information
+## Features
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+- **Workspace-aware**: Automatically discovers projects from `pnpm-workspace.yaml` or `package.json` workspaces
+- **Task caching**: Powered by `@visulima/task-runner` with local and remote caching support
+- **Dependency-aware scheduling**: Runs tasks in topological order with configurable parallelism
+- **Affected detection**: Only runs tasks for projects changed since a given git ref
+- **Pluggable installer**: Defaults to the lockfile-detected PM (pnpm/npm/yarn/bun); auto-uses [aube](https://github.com/endevco/aube) when on `PATH`, with a single switch (`install.backend` / `--installer` / `--no-aube`) to pin or bypass it
+- **Catalog management**: Check and update dependencies in pnpm/bun workspace catalogs
+- **Security scanning**: Check for known vulnerabilities via OSV.dev
+- **Graph visualization**: View your project dependency graph in ASCII, DOT, JSON, or HTML
+- **Git hooks**: Install, manage, and migrate git hooks (husky migration supported)
+- **Configurable**: `vis.json` for target defaults, cache settings, and task runner options
+- **Built on Cerebro**: Uses `@visulima/cerebro` for a robust CLI experience with built-in help, version, and completion
 
----
+## Install
+
+```sh
+npm install @visulima/vis
+```
+
+```sh
+yarn add @visulima/vis
+```
+
+```sh
+pnpm add @visulima/vis
+```
+
+### Cold start (no Node? no manager?)
+
+One-liner bootstrap that installs a version manager, Node LTS, and `vis` in one go.
+
+**Linux / macOS / WSL** (bash):
+
+```sh
+curl -fsSL https://visulima.com/install.sh | bash
+```
+
+**Windows** (PowerShell 5.1+):
+
+```powershell
+irm https://visulima.com/install.ps1 | iex
+```
+
+Pass `--yes --manager=proto` (POSIX) or `-Yes -Manager proto` (PowerShell) for non-interactive / CI usage. See [`vis toolchain` docs](./docs/commands/toolchain.mdx#cold-start--no-node-no-manager) for details.
+
+## Quick Start
+
+```bash
+# Run a target across all workspace projects
+vis run build
+
+# Run tests only on affected projects
+vis affected test --base=main
+
+# Visualize the project dependency graph
+vis graph
+
+# Check for outdated catalog dependencies
+vis check
+
+# Check with security vulnerability scanning
+vis check --security
+
+# Update catalog dependencies interactively
+vis update --interactive
+
+# Install git hooks
+vis hook install
+```
+
+## Installer backend (aube)
+
+`vis install`, `vis add`, `vis remove`, `vis update`, `vis dlx`, `vis exec`, `vis link`, `vis unlink`, `vis dedupe`, `vis why`, `vis outdated`, `vis info`, and `vis pm` honor [aube](https://github.com/endevco/aube) — a Rust-native package manager that reads and writes pnpm/npm/yarn/bun lockfiles in place — as a drop-in installer. Aube also supports the pnpm `catalog:` and `catalog:<name>` protocol from `pnpm-workspace.yaml`, including walk-up resolution from subpackages.
+
+`vis` does not bundle aube. Install it once via your tool of choice and `vis` will auto-detect it on `PATH`:
+
+```bash
+npm install -g @endevco/aube       # or
+mise use -g aube                   # or
+brew install endevco/tap/aube
+```
+
+Resolution precedence (highest first):
+
+1. `--installer <name>` CLI flag (or `--no-aube` to force the lockfile-detected PM for one run)
+2. `VIS_INSTALLER` environment variable
+3. `install.backend` in `vis.config.ts`
+4. Auto-detect — uses `aube` when it's on `PATH`, otherwise the lockfile-detected PM
+
+```ts
+// vis.config.ts — pin the installer for the team
+import { defineConfig } from "@visulima/vis/config";
+
+export default defineConfig({
+    install: { backend: "aube" }, // "auto" | "aube" | "pnpm" | "npm" | "yarn" | "bun"
+});
+```
+
+### Lockfile drift
+
+Aube reuses pnpm/npm/yarn/bun lockfile formats but its serialized output isn't byte-identical to the original tool's. The first install on a workspace whose lockfile was written by another PM produces a one-time churn diff; teams that mix tools on the same lockfile see ongoing drift. `vis install` warns when this is about to happen — pin `install.backend` to keep the team consistent.
+
+### Lifecycle scripts
+
+Aube already skips dependency lifecycle scripts by default. `--ignore-scripts` is a no-op under aube (`vis install` warns when you pass it). To opt specific packages back in, run `aube approve-builds` — the inverse direction from the pnpm/npm `--ignore-scripts` model.
+
+## Commands
+
+| Command                 | Alias  | Description                                                          |
+| ----------------------- | ------ | -------------------------------------------------------------------- |
+| `vis create [template]` |        | Scaffold a new project from templates, npm packages, or git repos    |
+| `vis generate [name]`   |        | Scaffold files from an in-repo template (native TS or moon-format)   |
+| `vis init`              |        | Initialize vis.config.ts with security defaults                      |
+| `vis run <target>`      |        | Run a target across workspace projects with caching                  |
+| `vis affected <target>` |        | Run tasks only on projects affected by git changes                   |
+| `vis ignore <project>`  |        | CI build gating for Vercel / Netlify "Ignored Build Step"            |
+| `vis graph`             |        | Visualize the project dependency graph                               |
+| `vis check [packages]`  | `c`    | Check for outdated dependencies in workspace catalogs                |
+| `vis update [packages]` | `up`   | Update packages to their latest versions                             |
+| `vis install`           | `i`    | Install dependencies via the detected package manager                |
+| `vis info <package>`    | `view` | Show npm registry metadata for a package (wraps `npm view` et al.)   |
+| `vis dlx <package>`     |        | Execute a remote package without permanent installation              |
+| `vis audit`             |        | Audit dependencies for security vulnerabilities                      |
+| `vis clean`             |        | Remove build artifacts, caches, and node_modules                     |
+| `vis cache <action>`    |        | Inspect cache (`list`, `size`, `hash`, `why`), or `prune` / `clean`  |
+| `vis hook <action>`     |        | Manage git hooks (install, uninstall, migrate)                       |
+| `vis secrets [paths]`   |        | Scan for hardcoded secrets / credentials (Rust-native)               |
+| `vis toolchain <cmd>`   |        | Inspect / delegate to the version manager (proto, mise, fnm, volta…) |
+| `vis staged`            |        | Run tasks on staged files (built-in `lint-staged` replacement)       |
+| `vis migrate <type>`    |        | Migrate from other tools — now including `gitleaks` and `secretlint` |
+
+For `vis ignore`, see the [command reference](./docs/commands/ignore.mdx) and the [deployment build gating section](./docs/guides/ci-cd.mdx#deployment-build-gating) of the CI/CD guide.
+
+### Diagnosing cache misses
+
+When a task you expected to be cached re-ran, ask vis what changed:
+
+```sh
+vis cache why @myorg/app:build           # human-friendly diff vs. previous run
+vis cache why @myorg/app:build --json    # stable shape for CI
+vis cache hash @myorg/app:build          # just print the hash + per-bucket inputs
+```
+
+`vis cache why` reads `.task-runner/last-summary.json` and diffs the task's `hashDetails` (`command`, `nodes`, `runtime`, `implicitDeps`) against the previous run, so you can pinpoint exactly which bucket rotated. Past runs only land in `.task-runner/runs/` when you pass `--summarize`, so use `vis run :build --summarize` (or set it as a default in CI) for diffs you'll want to inspect later.
+
+### Cache retention
+
+`vis cache prune` evicts entries by any combination of age, total size, and count:
+
+```sh
+vis cache prune --max-age-days=7              # drop entries older than a week
+vis cache prune --max-size=2GB                # evict oldest until under 2 GB
+vis cache prune --keep-last=30                # keep only the 30 newest entries
+vis cache prune --keep-last=30 --max-age-days=14   # combine: 30-newest floor, then age cap
+```
+
+`--keep-last` enforces a count floor first (newest-first by mtime), then `--max-age-days` and `--max-size` apply.
+
+### Sharing the cache across git worktrees
+
+When the workspace is a linked worktree (created with `git worktree add`), vis stores the cache at `<mainWorktreeRoot>/.task-runner-cache` so sibling worktrees driven by parallel agents share one cache instead of rebuilding the same hash N times. Set `sharedWorktreeCache: false` in `vis.config.ts` to opt out, or use `--scope=worktree|shared|all` on `vis cache list/size/prune` to inspect or operate on a specific store.
+
+### Quieting successful runs
+
+`--output-style=quiet` skips stdout/stderr from successful and cached tasks while keeping failures fully visible. Pair it with per-target `options.outputStyle` to mute a single noisy task — or to keep one critical task verbose under a global quiet flag:
+
+```sh
+vis run :build --output-style=quiet     # only failures print
+```
+
+```json
+{
+    "targets": {
+        "lint": { "options": { "outputStyle": "quiet" } },
+        "migrate": { "options": { "outputStyle": "normal" } }
+    }
+}
+```
+
+See the [`vis cache`](./docs/commands/cache.mdx) and [`vis run`](./docs/commands/run.mdx) command references for the full surface.
+
+### Scanning for secrets
+
+`vis secrets` wraps [`@visulima/secret-scanner`](../secret-scanner) — a Rust port of the gitleaks detection engine — with ergonomic flags for the common workflows.
+
+```sh
+vis secrets                         # scan the workspace (grouped, colourised output)
+vis secrets --staged                # pre-commit mode: scan staged files only
+vis secrets --since main            # scan files changed since the `main` branch
+vis secrets --affected              # scan only files affected by the current branch
+vis secrets --init                  # scaffold an initial .secrets-baseline.json
+vis secrets --list-rules            # print all bundled detection rules
+vis secrets --enable-rule tag:preset:weak-passwords  # enable an opt-in rule group additively
+vis secrets --exclude 'dist/**' --exclude-from .secretsignore    # extra walker exclusions
+vis secrets --include-rule stripe-access-token                   # check a single rule
+vis secrets --exclude-rule generic-api-key                       # drop a noisy rule
+vis secrets --baseline .secrets-baseline.json   # suppress triaged findings; print diff
+vis secrets --update-baseline       # merge current findings into the baseline
+vis secrets --format sarif > report.sarif       # SARIF for GitHub code-scanning
+```
+
+**Suppression** — inline (`// gitleaks:allow`), block (`gitleaks:allow-start` … `gitleaks:allow-end`), or a baseline JSON (sole fingerprint store). See the [secret-scanner README](../secret-scanner/README.md#suppression) for details.
+
+**CI example** (GitHub Actions, SARIF upload):
+
+```yaml
+name: Secrets
+on: [push, pull_request]
+jobs:
+    scan:
+        runs-on: ubuntu-latest
+        permissions: { security-events: write, contents: read }
+        steps:
+            - uses: actions/checkout@v4
+            - uses: pnpm/action-setup@v4
+            - run: pnpm install
+            - run: pnpm vis secrets --format sarif > report.sarif
+              continue-on-error: true
+            - uses: github/codeql-action/upload-sarif@v3
+              with: { sarif_file: report.sarif }
+```
+
+### Migrations
+
+`vis migrate` now speaks two security tools:
+
+```sh
+vis migrate gitleaks     # keeps gitleaks.toml, rewrites scripts/hooks to `vis secrets`
+vis migrate secretlint   # removes @secretlint/*, rewrites scripts/hooks, notes active rules
+```
+
+Every destructive step writes a `.bak` sidecar first and prompts for confirmation (skip with `-y`). Dry-run previews are available via `--dry-run`.
+
+### Running tasks on staged files
+
+`vis staged` is a built-in replacement for `lint-staged` — the same config shape, no peer dependency, and an integrated task renderer. Requires Git ≥ 2.32.
+
+Declare the patterns and tasks under `staged` in `vis.config.ts`:
+
+```ts
+// vis.config.ts
+import { defineConfig } from "@visulima/vis/config";
+
+export default defineConfig({
+    staged: {
+        "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+        "*.md": "prettier --write",
+        "package.json": (files) => `sort-package-json ${files.join(" ")}`,
+    },
+});
+```
+
+Each key is a glob (basename or path-style — path-style matches resolve relative to `cwd`). Each value is one of:
+
+- a command string — split into argv, invoked with matched files appended;
+- a `string[]` array — commands run serially for that pattern;
+- a function `(files) => string | string[] | {title, task}` — generate dynamic commands or a custom task;
+- a `{ title, task }` object — runs `task(files)` with no argv construction, useful for in-process side effects.
+
+`vis.config.ts` is the single source of truth — no standalone `.lintstagedrc*` or `.vis-staged.*` files are read at runtime. Migrating from lint-staged or nano-staged? Run `vis migrate lint-staged` (or `vis migrate nano-staged`) to move the config in and remove the legacy files.
+
+#### Command-line flags
+
+```sh
+vis staged                          # run tasks on the current staged set
+vis staged --verbose                # show stdout/stderr on success as well as failure
+vis staged --no-stash               # skip the backup stash (faster, but no recovery on failure)
+vis staged --diff HEAD~1            # operate on a range instead of `--staged`
+vis staged --diff-filter=ACM        # override the default ACMR filter
+vis staged --concurrent 4           # cap parallel pattern execution
+vis staged --continue-on-error      # don't short-circuit on the first failure
+vis staged --fail-on-changes        # non-zero exit if tasks modified staged content
+vis staged --hide-unstaged          # hide all unstaged edits on tracked files
+vis staged --hide-all               # hide unstaged edits AND untracked files
+vis staged --relative               # pass paths relative to cwd to tasks
+vis staged --revert                 # restore pre-task state on failure
+vis staged --allow-empty            # allow a commit when tasks revert everything
+vis staged --auto-stage             # auto-stage new files tasks create (codegen, lockfile regen, …)
+vis staged --force-kill             # kill in-flight tasks with SIGKILL on fast-fail (default: SIGTERM)
+```
+
+#### Environment variables
+
+| Variable                | Description                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VIS_STAGED_CONCURRENT` | Concurrency fallback when `--concurrent` is not passed. Same value shape as the flag (`true`, `false`, or an integer). Useful in CI so you don't repeat the flag on every invocation. |
+
+#### How it behaves
+
+1. A hidden backup stash is created (via `git stash create` + `git stash store`, so the working tree is untouched).
+2. For partially-staged files, the unstaged delta is captured as a patch and the working tree is reset to the staged content. `--hide-all` extends this to every unstaged change _and_ untracked files via a single `git stash push --include-untracked`.
+3. Tasks run — patterns in parallel (capped at `os.availableParallelism()` by default), commands within a pattern serially.
+4. Task-driven edits are re-staged with `git update-index --again` (with a `git add -u` fallback for deletions), so commits made via pathspec (`git commit -m "…" .`) keep working.
+5. The unstaged patch — or the hide-all stash — is re-applied and the backup stash is dropped on success. On failure without `--revert`, the backup stash is preserved and the recovery sha is surfaced to the user. Ctrl+C aborts in-flight commands and still runs the restore path; a second Ctrl+C exits immediately.
+
+#### Migrating from lint-staged
+
+```sh
+vis migrate lint-staged    # moves the config into vis.config.ts and rewrites hooks
+```
+
+The migrator detects `package.json` keys, `.lintstagedrc*` files, and `lint-staged.config.*`, prompts before rewriting husky/vis hooks to call `vis staged`, and removes `lint-staged` from the dependency list.
+
+## Documentation
+
+For full documentation including command reference, configuration options, best practices, and CI/CD integration guides, see the [docs](./docs) folder.
+
+## Supported Node.js Versions
+
+Libraries in this ecosystem make the best effort to track [Node.js' release schedule](https://github.com/nodejs/release#release-schedule).
+Here's [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
+
+## Contributing
+
+If you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](.github/CONTRIBUTING.md) guidelines.
+
+> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
+
+## Credits
+
+- [Daniel Bannert](https://github.com/prisis)
+- [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
+
+## Made with ❤️ at Anolilab
+
+This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!
+
+## License
+
+The visulima vis is open-sourced software licensed under the [MIT][license]
+
+<!-- badges -->
 
-**Maintained for OIDC setup purposes only**
+[license-badge]: https://img.shields.io/npm/l/@visulima/vis?style=for-the-badge
+[license]: https://github.com/visulima/visulima/blob/main/LICENSE
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/vis?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@visulima/vis
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md
+[chat-badge]: https://img.shields.io/discord/932323359193186354.svg?style=for-the-badge
+[chat]: https://discord.gg/TtFJY8xkFK
+[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/

package/dist/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import"@visulima/cerebro";import"@visulima/cerebro/command/completion";import"@visulima/cerebro/compile-cache";import"@visulima/cerebro/heap-tuning";import"@visulima/cerebro/plugins/error-handler";import"@visulima/fs";import"@visulima/package";import"@visulima/path";import"./packem_chunks/bin.js";

package/dist/errors/index.d.ts

@@ -0,0 +1,26 @@
+/**
+* Base class for all `vis.config.ts` / `vis.task.ts` loader failures.
+* Consumers switch on `instanceof VisConfigError` to distinguish loader
+* failures from arbitrary user-code exceptions thrown inside a config.
+*/
+declare class VisConfigError extends Error {
+  readonly chain: ReadonlyArray<string>;
+  constructor(message: string, chain: ReadonlyArray<string>, options?: ErrorOptions);
+}
+/** An `extends` chain re-enters a path that is still loading. */
+declare class VisConfigCycleError extends VisConfigError {
+  constructor(reentered: string, chain: ReadonlyArray<string>);
+}
+/**
+* Wraps any throw raised by jiti while compiling a `vis.config.ts` /
+* `vis.task.ts`. Without this wrapper a user's syntax error surfaces as
+* "TypeError in workspace.ts" — which sends them debugging the wrong file.
+*/
+declare class VisConfigLoadError extends VisConfigError {
+  constructor(filePath: string, chain: ReadonlyArray<string>, cause: unknown);
+}
+/** An entry in `extends` could not be resolved on disk or via npm. */
+declare class VisConfigNotFoundError extends VisConfigError {
+  constructor(specifier: string, chain: ReadonlyArray<string>, attempted: ReadonlyArray<string>);
+}
+export { VisConfigCycleError, VisConfigError, VisConfigLoadError, VisConfigNotFoundError };

package/dist/errors/index.js

@@ -0,0 +1 @@
+import{VisConfigCycleError as f}from"../packem_shared/VisConfigCycleError-CAYNC7d-.js";import{VisConfigError as e}from"../packem_shared/VisConfigError-B5LP1zRf.js";import{VisConfigLoadError as t}from"../packem_shared/VisConfigLoadError-CeqBSd2Z.js";import{VisConfigNotFoundError as g}from"../packem_shared/VisConfigNotFoundError-DZ9KC527.js";export{f as VisConfigCycleError,e as VisConfigError,t as VisConfigLoadError,g as VisConfigNotFoundError};

package/dist/generate/index.d.ts

@@ -0,0 +1,157 @@
+/**
+* Type definitions for the `vis generate` template runtime.
+*
+* The shape intentionally echoes Bingo's `Template` so a future Bingo
+* adapter (re-exporting `bingo` Templates through this runtime) is a
+* one-pager. Authors do not depend on Bingo to write a vis generator.
+*/
+type VariableType = "array" | "boolean" | "enum" | "number" | "string";
+/** Common variable fields (all types). */
+interface VariableBase {
+  /**
+  * Default value when the user accepts the prompt without typing.
+  * For `boolean` this is `true|false`; for `enum` it must match `values`.
+  */
+  default?: boolean | number | string | string[];
+  /** Hide from prompts; can still be set via CLI or `--defaults`. */
+  internal?: boolean;
+  /** Sort order in prompts (lower first). Defaults to declaration order. */
+  order?: number;
+  /** Override the prompt text. Defaults to the variable name. */
+  prompt?: string;
+  /** When true, the user must provide a non-empty value. */
+  required?: boolean;
+}
+type StringVariable = VariableBase & {
+  type: "string";
+};
+type NumberVariable = VariableBase & {
+  type: "number";
+};
+type BooleanVariable = VariableBase & {
+  default?: boolean;
+  type: "boolean";
+};
+type ArrayVariable = VariableBase & {
+  type: "array";
+};
+interface EnumVariable extends VariableBase {
+  /** Allow multiple selections (returns `string[]`). */
+  multiple?: boolean;
+  type: "enum";
+  /** Selectable values. */
+  values: string[];
+}
+type Variable = ArrayVariable | BooleanVariable | EnumVariable | NumberVariable | StringVariable;
+/** Map of variable name → spec, as authors declare them. */
+type VariableMap = Record<string, Variable>;
+/** Resolved option values passed to `produce()`. */
+type Options = Record<string, unknown>;
+/** A file in a Creation can be a string, a Buffer (binary asset), or a nested directory. */
+type CreationFile = Buffer | string;
+interface CreationDirectory {
+  [key: string]: CreationDirectory | CreationFile;
+}
+/**
+* Script entry produced by `produce()`.
+* - `string`: shell command, runs in the destination directory.
+* - `object`: shell commands with optional phase ordering.
+*/
+type Script = ScriptObject | string;
+interface ScriptObject {
+  /** Shell command(s) to run sequentially. */
+  commands: string[];
+  /**
+  * Phase ordering. Phases run in ascending order; scripts within
+  * the same phase are dispatched concurrently. Default: 0.
+  */
+  phase?: number;
+  /** Suppress command output. Default: false. */
+  silent?: boolean;
+}
+/** Object returned by a template's `produce()` function. */
+interface Creation {
+  /** Recursive directory tree. Keys with `/` are auto-split. */
+  files?: CreationDirectory;
+  /**
+  * Per-file metadata keyed by the *flattened* destination path
+  * (e.g. `src/foo.ts`). Optional — native templates usually omit
+  * this; the moon adapter populates it from per-file frontmatter
+  * so `force: true` survives the trip to the runner without
+  * changing the shape of `files`.
+  */
+  filesMeta?: Record<string, FileMeta>;
+  /** Shell scripts to run after files are written. */
+  scripts?: Script[];
+  /** User-facing tips printed after the run. */
+  suggestions?: string[];
+}
+interface FileMeta {
+  /**
+  * Overwrite an existing file at this path without prompting or
+  * consulting the global `--force` flag.
+  */
+  force?: boolean;
+}
+/** Context object passed to `produce()`. */
+interface TemplateContext {
+  /** Built-in variables: `dest_dir`, `dest_rel_dir`, `working_dir`, `workspace_root`. */
+  builtins: BuiltinVars;
+  /** Resolved option values (after prompts + CLI overrides + defaults). */
+  options: Options;
+}
+interface BuiltinVars {
+  /** Absolute destination directory. */
+  dest_dir: string;
+  /** Destination relative to the workspace root. */
+  dest_rel_dir: string;
+  /** Caller's current working directory. */
+  working_dir: string;
+  /** Absolute workspace root (from `findMonorepoRootSync`, fallback to `working_dir`). */
+  workspace_root: string;
+}
+/** Top-level "About" metadata for a template. */
+interface TemplateAbout {
+  /** One-line description. */
+  description: string;
+  /** Short identifier shown in `vis generate --list` and prompts. */
+  name: string;
+}
+/**
+* The author-facing template shape.
+* Both native (`.vis/templates/&lt;name>.ts`) and moon-adapter outputs
+* normalize to this.
+*/
+interface Template {
+  about: TemplateAbout;
+  /**
+  * Default destination directory (relative to workspace root unless
+  * absolute or starting with `./`). Honored when the user does not
+  * pass `--to`. Maps to moon's `template.yml` `destination`.
+  */
+  destination?: string;
+  /** Variable schema for prompts. */
+  options?: VariableMap;
+  /** Build the Creation given resolved options and built-in vars. */
+  produce: (context: TemplateContext) => Creation | Promise<Creation>;
+}
+/**
+* Discovery record: a Template plus where it came from.
+* Surfaced by `vis generate --list`.
+*/
+interface DiscoveredTemplate {
+  /** Lazy loader — invoke to materialize the Template. */
+  load: () => Promise<Template>;
+  /** Stable name used by `vis generate &lt;name>`. */
+  name: string;
+  /** Absolute path on disk (file for native, directory for moon). */
+  path: string;
+  /** Source classification — affects load + listing. */
+  source: "config" | "moon" | "native" | "remote";
+}
+/**
+* Identity helper for type inference. Authors get autocomplete + checks
+* without having to annotate the export.
+*/
+declare const createTemplate: (template: Template) => Template;
+export { type ArrayVariable, type BooleanVariable, type BuiltinVars, type Creation, type CreationDirectory, type CreationFile, type DiscoveredTemplate, type EnumVariable, type FileMeta, type NumberVariable, type Options, type Script, type ScriptObject, type StringVariable, type Template, type TemplateAbout, type TemplateContext, type Variable, type VariableMap, type VariableType, createTemplate };

package/dist/generate/index.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var r=(e,a)=>t(e,"name",{value:a,configurable:!0});var c=Object.defineProperty,l=r((e,a)=>c(e,"name",{value:a,configurable:!0}),"a");const o=l(e=>e,"createTemplate");export{o as createTemplate};