@visulima/vis 1.0.0-alpha.5 → 1.0.0-alpha.6

package/dist/generate/prompts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Variable-schema → interactive prompts.
+ *
+ * Builds on the same `node:readline` helpers `vis create` uses (see
+ * src/commands/create/prompts.ts). The implementation is minimal — no
+ * fancy multi-line UI, no spinner, no terminal control codes — to
+ * stay consistent with the rest of the vis CLI surface.
+ */
+import type { Options, VariableMap } from "./types.d.ts";
+interface CollectOptions {
+    /** When true, skip prompts and use defaults / overrides only. */
+    defaults: boolean;
+    /** When false, never prompt — error on missing required values. */
+    interactive: boolean;
+    /** CLI overrides — variable name → unparsed string from `--name=value`. */
+    overrides: Record<string, string>;
+    /** Variable schema. */
+    variables: VariableMap;
+}
+/**
+ * Collect option values from prompts + CLI overrides + defaults, then
+ * validate them.
+ */
+export declare const collectOptions: (collectOptionsArguments: CollectOptions) => Promise<Options>;
+export {};

package/dist/generate/remote.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Remote template fetching for `vis generate`.
+ *
+ * Reuses giget (already a vis dep, used by `vis create`) to fetch
+ * `git://`, `npm://`, and `https://` archive sources into a cache
+ * directory before discover/load runs against them.
+ *
+ * Sources are normalized via the same patterns vis create uses; see
+ * `src/commands/create/templates/remote.ts` for the underlying
+ * downloadTemplate call.
+ */
+/**
+ * True when the input looks like a remote source giget can resolve.
+ */
+export declare const isRemoteSource: (input: string) => boolean;
+interface FetchOptions {
+    /** Auth token forwarded to giget for private repos. */
+    auth?: string;
+    /** Prefer cached templates over re-download. */
+    preferOffline?: boolean;
+    /** Override the cache/work directory (defaults to a fresh tmp). */
+    targetDirectory?: string;
+}
+export interface FetchResult {
+    /**
+     * Release the tmp directory once the caller has finished loading
+     * the template into memory. No-op when the directory was supplied
+     * externally via `targetDirectory`.
+     */
+    cleanup: () => void;
+    /** Absolute directory containing the downloaded template. */
+    directory: string;
+}
+/**
+ * Download a remote template and return the directory it lives in.
+ * @example
+ * ```typescript
+ * const { directory } = await fetchRemoteTemplate("git://github.com/org/template#main");
+ * const template = await loadMoonTemplate(directory, "from-git");
+ * ```
+ */
+export declare const fetchRemoteTemplate: (source: string, options?: FetchOptions) => Promise<FetchResult>;
+export {};

package/dist/generate/runner.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Template runner — applies a `Creation` to disk.
+ *
+ * Walks the recursive `files` tree, prompts for overwrites unless
+ * `--force` was passed, runs scripts in phase order, and prints
+ * suggestions at the end. `--dry-run` prints the planned writes
+ * without touching the filesystem.
+ *
+ * Every write target is checked against the destination directory to
+ * reject `..`-escapes and absolute paths coming from rendered
+ * frontmatter `to:` fields or filename interpolation — template
+ * authors (or remote templates) must not be able to scribble
+ * outside the caller's chosen destination.
+ */
+import type { Template } from "./types.d.ts";
+interface RunnerOptions {
+    /** Caller's CWD for `working_dir`. */
+    cwd: string;
+    /** Destination directory (absolute). */
+    destination: string;
+    /** When true, print but don't write. */
+    dryRun?: boolean;
+    /** When true, overwrite existing files without prompting. */
+    force?: boolean;
+    /** Resolved option values from `collectOptions`. */
+    options: Record<string, unknown>;
+    /** When true, don't run scripts. */
+    skipScripts?: boolean;
+    /** Workspace root for `dest_rel_dir`. */
+    workspaceRoot: string;
+}
+/**
+ * Run a template end-to-end: invoke `produce`, write files, run scripts,
+ * print suggestions.
+ */
+export declare const runTemplate: (template: Template, options: RunnerOptions) => Promise<void>;
+export {};

package/dist/generate/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+export 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;
+}
+export type StringVariable = VariableBase & {
+    type: "string";
+};
+export type NumberVariable = VariableBase & {
+    type: "number";
+};
+export type BooleanVariable = VariableBase & {
+    default?: boolean;
+    type: "boolean";
+};
+export type ArrayVariable = VariableBase & {
+    type: "array";
+};
+export interface EnumVariable extends VariableBase {
+    /** Allow multiple selections (returns `string[]`). */
+    multiple?: boolean;
+    type: "enum";
+    /** Selectable values. */
+    values: string[];
+}
+export type Variable = ArrayVariable | BooleanVariable | EnumVariable | NumberVariable | StringVariable;
+/** Map of variable name → spec, as authors declare them. */
+export type VariableMap = Record<string, Variable>;
+/** Resolved option values passed to `produce()`. */
+export type Options = Record<string, unknown>;
+/** A file in a Creation can be a string, a Buffer (binary asset), or a nested directory. */
+export type CreationFile = Buffer | string;
+export 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.
+ */
+export type Script = ScriptObject | string;
+export 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. */
+export 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[];
+}
+export interface FileMeta {
+    /**
+     * Overwrite an existing file at this path without prompting or
+     * consulting the global `--force` flag.
+     */
+    force?: boolean;
+}
+/** Context object passed to `produce()`. */
+export 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;
+}
+export 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. */
+export 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.
+ */
+export 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`.
+ */
+export 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";
+}
+export {};

package/dist/hooks.d.ts

@@ -0,0 +1,118 @@
+import type { LifeCycleInterface, Task, TaskResult } from "@visulima/task-runner";
+import type { Hookable } from "hookable";
+/**
+ * Typed hook surface exposed to vis plugins.
+ *
+ * Plugins subscribe via `hooks.hook(name, handler)` — handlers are
+ * awaited sequentially in registration order. Returning a promise
+ * delays the next hook firing until it resolves, so plugins can
+ * safely perform async setup/teardown.
+ *
+ * Naming deliberately mirrors vite-task / webpack-style verbs:
+ *   before/after for boundaries, on<Event> for passive observation.
+ */
+export interface VisHooks {
+    /**
+     * Fired after the entire task graph completes (including any
+     * failures). `results` maps task ID → {@link TaskResult}.
+     */
+    "run:after": (results: Map<string, TaskResult>) => Promise<void> | void;
+    /**
+     * Fired once before any task in the graph starts, after workspace
+     * discovery and graph construction. Throwing aborts the run.
+     */
+    "run:before": (context: {
+        tasks: Task[];
+        workspaceRoot: string;
+    }) => Promise<void> | void;
+    /**
+     * Fired after a task completes (success, failure, or cache hit).
+     * Receives the final {@link TaskResult}.
+     */
+    "task:after": (task: Task, result: TaskResult) => Promise<void> | void;
+    /**
+     * Fired before each task begins execution — after scheduling, before
+     * the executor runs the command. Throwing aborts that single task.
+     */
+    "task:before": (task: Task) => Promise<void> | void;
+    /** Fired when a task hit the local or remote cache. */
+    "task:cacheHit": (task: Task, result: TaskResult) => Promise<void> | void;
+    /**
+     * Fired when auto-fingerprint cache diagnostics reports a miss,
+     * carrying the human-readable reason string.
+     */
+    "task:cacheMiss": (task: Task, reasons: string) => Promise<void> | void;
+    /** Fired when a task exits non-zero. */
+    "task:failure": (task: Task, result: TaskResult) => Promise<void> | void;
+    /**
+     * Fired with a stderr chunk as a running task emits it. Plugins
+     * that ship logs live (Slack, Datadog) should prefer this over
+     * `task:after` so they don't wait for the full buffer.
+     */
+    "task:stderr": (task: Task, chunk: string) => Promise<void> | void;
+    /**
+     * Fired with a stdout chunk as a running task emits it. See
+     * `task:stderr` for semantics.
+     */
+    "task:stdout": (task: Task, chunk: string) => Promise<void> | void;
+}
+/**
+ * Public plugin contract. Implementations register handlers by
+ * returning a partial {@link VisHooks} map from `hooks`, or by
+ * mutating the Hookable instance directly via `setup(hooks)` for
+ * advanced cases (dynamic registration, removeHook, etc.).
+ *
+ * Plugins are loaded in the order they appear in `visConfig.plugins`.
+ * Handler execution order within a hook follows registration order,
+ * so earlier plugins see events first.
+ */
+export interface VisPlugin {
+    /**
+     * Declarative handlers — the common shape. One entry per hook
+     * name; pass a function or an array of functions (all run serially
+     * in order).
+     */
+    hooks?: Partial<{
+        [K in keyof VisHooks]: VisHooks[K] | VisHooks[K][];
+    }>;
+    /** Plugin name — surfaced in debug logs. */
+    name: string;
+    /**
+     * Imperative setup — receives the shared Hookable instance so the
+     * plugin can register hooks conditionally, unregister later, or
+     * use advanced APIs like `hookOnce`/`beforeEach`/`afterEach`.
+     */
+    setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
+}
+/**
+ * Optional callback invoked whenever a plugin handler throws. Lets
+ * callers surface buggy plugins without crashing the run — pass a
+ * logger or re-throw to promote plugin errors to fatals.
+ */
+export type HookErrorHandler = (hookName: keyof VisHooks, error: unknown) => void;
+/**
+ * Creates a fresh typed hook registry. One instance is created per
+ * `vis run` invocation and passed to every plugin's `setup()`.
+ */
+export declare const createVisHooks: () => Hookable<VisHooks>;
+/**
+ * Registers each plugin's handlers against the shared hook instance.
+ * Synchronous failures in `setup()` abort plugin loading and propagate.
+ */
+export declare const registerPlugins: (hooks: Hookable<VisHooks>, plugins: VisPlugin[] | undefined) => Promise<void>;
+/**
+ * Bridges `LifeCycleInterface` (the task-runner contract) into
+ * `VisHooks` events. Register this as a lifecycle alongside the
+ * existing UI renderers so plugin authors see the same events the
+ * TUI/static output do, without having to understand task-runner's
+ * lower-level `LifeCycleInterface` shape.
+ */
+export declare class HookableLifeCycle implements LifeCycleInterface {
+    #private;
+    constructor(hooks: Hookable<VisHooks>, onError?: HookErrorHandler);
+    startTasks(tasks: Task[]): void;
+    endTasks(results: TaskResult[]): void;
+    printCacheMiss(task: Task, reasons: string): void;
+    onTaskStdout(task: Task, chunk: string): void;
+    onTaskStderr(task: Task, chunk: string): void;
+}

package/dist/native-binding.d.ts

@@ -121,12 +121,19 @@ interface NativeBindings {
     detectPackageManager: (cwd: string) => DetectedPackageManager;
     execPmCommand: (bin: string, args: string[], cwd: string) => ExecResult;
     execPmCommandInteractive: (bin: string, args: string[], cwd: string) => number;
+    /**
+     * ABI compatibility version exported from the Rust binding. The TypeScript
+     * loader compares this against {@link EXPECTED_NATIVE_BINDING_VERSION} and
+     * rejects mismatched addons so a stale `.node` file from before a
+     * signature change is not used silently.
+     */
+    NATIVE_BINDING_VERSION: number;
     resolveAdd: (pm: string, version: string, options: AddOptions) => ResolvedCommand;
     resolveDedupe: (pm: string, version: string, check: boolean) => ResolvedCommand;
     resolveDlx: (pm: string, version: string, options: DlxOptions) => ResolvedCommand;
     resolveExec: (pm: string, version: string, options: ExecOptions) => ResolvedCommand;
     resolveInstall: (pm: string, version: string, options: InstallOptions) => ResolvedCommand;
-    resolveLink: (pm: string, target: string | null) => ResolvedCommand;
+    resolveLink: (pm: string, version: string, target: string | null) => ResolvedCommand;
     resolveOutdated: (pm: string, version: string, options: OutdatedOptions) => ResolvedCommand;
     resolvePmCommand: (pm: string, version: string, subcommand: string, extraArgs: string[]) => ResolvedCommand;
     resolveRemove: (pm: string, version: string, options: RemoveOptions) => ResolvedCommand;

package/dist/packem_chunks/index.js

@@ -0,0 +1,7 @@
+var H=Object.defineProperty;var v=(e,t)=>H(e,"name",{value:t,configurable:!0});import{walkSync as J,readFileSync as k}from"@visulima/fs";import{readYamlSync as X}from"@visulima/fs/yaml";import{relative as M,join as R}from"@visulima/path";import{parse as Z}from"yaml";import{constantCase as ee,trainCase as te,snakeCase as ne,pascalCase as re,kebabCase as ie,camelCase as se}from"@visulima/string/case";var ae=Object.defineProperty,d=v((e,t)=>ae(e,"name",{value:t,configurable:!0}),"e");const h=d(e=>e==null?"":typeof e=="string"?e:String(e),"stringify"),S={camel_case:d(e=>se(h(e)),"camel_case"),kebab_case:d(e=>ie(h(e)),"kebab_case"),lower_case:d(e=>h(e).toLowerCase(),"lower_case"),pascal_case:d(e=>re(h(e)),"pascal_case"),path_join:d((e,...t)=>{const r=[h(e),...t.map(h)];return R(...r)},"path_join"),path_relative:d((e,t)=>M(h(t),h(e)),"path_relative"),snake_case:d(e=>ne(h(e)),"snake_case"),upper_case:d(e=>h(e).toUpperCase(),"upper_case"),upper_kebab_case:d(e=>te(h(e)),"upper_kebab_case"),upper_snake_case:d(e=>ee(h(e)),"upper_snake_case")};d(e=>Object.hasOwn(S,e),"isKnownFilter");const I=d((e,t,r=[])=>{const n=S[e];if(!n)throw new Error(`Unknown filter "${e}". Known filters: ${Object.keys(S).sort().join(", ")}.`);return n(t,...r)},"applyFilter");var oe=Object.defineProperty,N=v((e,t)=>oe(e,"name",{value:t,configurable:!0}),"d$1");const L=N(e=>{const t=[];let r=0,n=0,i,s=-1;for(const a of e){if(s+=1,i){a===i&&(i=void 0);continue}if(a==='"'||a==="'"){i=a;continue}a==="("?r+=1:a===")"?r-=1:a===","&&r===0&&(t.push(e.slice(n,s)),n=s+1)}return t.push(e.slice(n)),t},"splitCommaOutsideQuotes"),le=N(e=>{if(e.startsWith('"')&&e.endsWith('"')||e.startsWith("'")&&e.endsWith("'"))return e.slice(1,-1)},"stripQuotes");var ce=Object.defineProperty,$=v((e,t)=>ce(e,"name",{value:t,configurable:!0}),"i$1");const fe=/\[([^\]]+)\]/g,ue=$(e=>{const t=e.trim(),r=t.indexOf("(");if(r===-1)return{args:[],name:t};if(!t.endsWith(")"))throw new Error(`Filter call "${e}" missing closing ")"`);const n=t.slice(0,r).trim(),i=t.slice(r+1,-1).trim();return i===""?{args:[],name:n}:{args:L(i).map(s=>{const a=s.trim();return le(a)??a}),name:n}},"parseFilterCall"),pe=$(e=>{const t=e.split("|").map(n=>n.trim()),r=t[0]??"";if(!r)throw new Error(`Empty variable name in expression "${e}"`);return{filters:t.slice(1).map(ue),name:r}},"parsePipe"),me=$(e=>e==null?"":typeof e=="string"?e:String(e),"stringify"),de=$((e,t)=>{const r=e.replaceAll(fe,(n,i)=>{const{filters:s,name:a}=pe(i);if(!Object.hasOwn(t,a))throw new Error(`Variable "${a}" used in filename "${e}" but not defined`);let o=t[a];for(const l of s)o=I(l.name,o,l.args);return me(o)});return q(r)},"interpolateFilename"),q=$(e=>e.split("/").map(t=>t.endsWith(".tera")||t.endsWith(".twig")?t.slice(0,-5):t).join("/"),"stripTeraSuffix"),he=$(e=>e.endsWith(".raw")?e.slice(0,-4):e,"stripRawSuffix"),ye=$(e=>{const t=e.split("/");return(t.at(-1)??"").startsWith("_")?!0:t.slice(0,-1).includes("partials")},"isPartialPath");var ge=Object.defineProperty,be=v((e,t)=>ge(e,"name",{value:t,configurable:!0}),"i");const we=be((e,t)=>{if(!e.startsWith(`---
+`)&&!e.startsWith(`---\r
+`))return{body:e};const r=e.indexOf(`
+---`,3);if(r===-1)return{body:e};let n=r+1+3;e[n]==="\r"&&(n+=1),e[n]===`
+`&&(n+=1);const i=e.startsWith(`---\r
+`)?5:4,s=e.slice(i,r).replaceAll("\r","");let a;try{a=t(s)}catch(o){const l=o instanceof Error?o.message:String(o);throw new Error(`Failed to parse frontmatter YAML: ${l}`)}if(a==null)return{body:e.slice(n)};if(typeof a!="object"||Array.isArray(a))throw new TypeError(`Frontmatter must be a YAML mapping, got ${Array.isArray(a)?"array":typeof a}`);return{body:e.slice(n),frontmatter:a}},"splitFrontmatter");var ve=Object.defineProperty,f=v((e,t)=>ve(e,"name",{value:t,configurable:!0}),"c");const $e=/\{\{-?(.+?)-?\}\}|\{%-?(.+?)-?%\}/gs,U=f(e=>{const t=[];let r=0,n=1;const i=f(s=>{for(const a of s)a===`
+`&&(n+=1)},"advanceLine");for(const s of e.matchAll($e)){const a=s.index??0;if(a>r){const c=e.slice(r,a);t.push({line:n,type:"text",value:c}),i(c)}const o=n,l=s[0];l.startsWith("{{")?t.push({line:o,type:"expr",value:(s[1]??"").trim()}):t.push({line:o,type:"stmt",value:(s[2]??"").trim()}),i(l),r=a+l.length}if(r<e.length){const s=e.slice(r);t.push({line:n,type:"text",value:s})}return t},"tokenize"),xe=new Set(["block","endblock","endfilter","endmacro","extends","filter","import","macro","set"]),G=f((e,t)=>{let r=0;const n=f((s,a)=>{throw new Error(`${t}:${s}: ${a}`)},"error"),i=f(s=>{const a=[];for(;r<e.length;){const o=e[r];if(o.type==="text"){a.push({type:"text",value:o.value}),r+=1;continue}if(o.type==="expr"){a.push({expression:o.value,line:o.line,type:"expr"}),r+=1;continue}const l=o.value.split(/\s+/)[0]??"";if(s.includes(l))return a;if(xe.has(l)&&n(o.line,`Tera feature "{% ${l} %}" is not supported. Supported: if/else/endif, for/endfor, include. Rewrite the template to avoid macros, set, extends, block, and import.`),l==="if"){r+=1;const c=o.value.slice(2).trim(),m=i(["else","endif"]);let u;r<e.length&&e[r].type==="stmt"&&e[r].value.split(/\s+/)[0]==="else"&&(r+=1,u=i(["endif"])),(r>=e.length||e[r].type!=="stmt"||e[r].value.split(/\s+/)[0]!=="endif")&&n(o.line,"Unterminated {% if %} — missing {% endif %}"),r+=1,a.push({alternate:u,condition:c,consequent:m,line:o.line,type:"if"});continue}if(l==="for"){r+=1;const c=o.value.slice(3).trim(),m=c.indexOf(" in ");m===-1&&n(o.line,"Malformed {% for %} — expected `for <name> in <collection>`");const u=c.slice(0,m).trim(),g=c.slice(m+4).trim();(!u||!g)&&n(o.line,"Malformed {% for %} — missing binding or collection");const p=i(["endfor"]);(r>=e.length||e[r].type!=="stmt"||e[r].value.split(/\s+/)[0]!=="endfor")&&n(o.line,"Unterminated {% for %} — missing {% endfor %}"),r+=1,a.push({binding:u,body:p,collection:g,line:o.line,type:"for"});continue}if(l==="include"){r+=1;const c=o.value.slice(7).trim(),m=Q(c);m===void 0&&n(o.line,"Malformed {% include %} — expected a quoted partial name"),a.push({line:o.line,name:m,type:"include"});continue}n(o.line,`Unknown tag "{% ${l} %}". Supported: if, for, include.`)}return a},"parseBlock");return i([])},"parse"),Q=f(e=>{if(e.startsWith('"')&&e.endsWith('"')||e.startsWith("'")&&e.endsWith("'"))return e.slice(1,-1)},"stripQuotes"),Ee=f(e=>e==null?"":typeof e=="boolean"||typeof e=="number"?String(e):typeof e=="string"?e:JSON.stringify(e),"stringify"),Oe=f(e=>e==null||e===!1||e===0||e===""?!1:Array.isArray(e)?e.length>0:!0,"isTruthy"),V=f((e,t,r,n,i=!0)=>{const s=e.split(".");if(i&&s.length>0&&!Object.hasOwn(t,s[0]))throw new Error(`${n}:${r}: Variable "${e}" is not defined`);let a=t;for(const o of s){if(a==null)return;if(typeof a!="object")throw new TypeError(`${n}:${r}: Cannot read "${o}" on non-object value`);a=a[o]}return a},"lookupVariable"),ke=f(e=>{const t=[];let r=0,n=0,i;for(let s=0;s<e.length;s+=1){const a=e[s];if(i){a===i&&(i=void 0);continue}if(a==='"'||a==="'"){i=a;continue}a==="("?r+=1:a===")"?r-=1:a==="|"&&r===0&&(t.push(e.slice(n,s)),n=s+1)}return t.push(e.slice(n)),t},"splitFilterPipe"),je=f(e=>{const t=e.trim(),r=t.indexOf("(");if(r===-1)return{args:[],name:t};if(!t.endsWith(")"))throw new Error(`Filter call "${e}" missing closing ")"`);const n=t.slice(0,r).trim(),i=t.slice(r+1,-1).trim();return i?{args:L(i).map(s=>s.trim()),name:n}:{args:[],name:n}},"parseFilterCall"),j=f((e,t,r,n,i=!0)=>{const s=e.trim();if(s==="true")return!0;if(s==="false")return!1;if(s==="null"||s==="none")return null;const a=Q(s);return a!==void 0?a:/^-?\d+(\.\d+)?$/.test(s)?Number(s):V(s,t,r,n,i)},"evaluatePrimary"),B=f((e,t,r,n,i=!0)=>{const s=ke(e),a=s[0].trim();let o=j(a,t,r,n,i);for(let l=1;l<s.length;l+=1){const c=s[l].trim(),{args:m,name:u}=je(c),g=m.map(p=>j(p,t,r,n,i));try{o=I(u,o,g)}catch(p){const w=p instanceof Error?p.message:String(p);throw new Error(`${n}:${r}: ${w}`)}}return o},"evaluateExpression"),D=f((e,t)=>{let r,n=0;for(let i=0;i<=e.length-t.length;i+=1){const s=e[i];if(r){s===r&&(r=void 0);continue}if(s==='"'||s==="'"){r=s;continue}if(s==="("){n+=1;continue}if(s===")"){n-=1;continue}if(n===0&&e.slice(i,i+t.length)===t)return i}return-1},"findOperatorOutsideQuotes"),A=f((e,t)=>{const r=[];let n=0,i=0;for(;i<=e.length-t.length;){const s=D(e.slice(i),t);if(s===-1)break;r.push(e.slice(n,i+s)),i+=s+t.length,n=i}return r.push(e.slice(n)),r},"splitLogical"),x=f((e,t,r,n)=>{const i=e.trim();if(i==="")return!1;if(i.startsWith("(")&&i.endsWith(")")&&Se(i)===i.length-1)return x(i.slice(1,-1),t,r,n);const s=A(i," or ");if(s.length>1)return s.some(o=>x(o,t,r,n));const a=A(i," and ");if(a.length>1)return a.every(o=>x(o,t,r,n));if(i.startsWith("not "))return!x(i.slice(4),t,r,n);for(const o of["==","!="]){const l=D(i,o);if(l!==-1){const c=j(i.slice(0,l),t,n,r,!1),m=j(i.slice(l+o.length),t,n,r,!1),u=c===m;return o==="=="?u:!u}}return Oe(B(i,t,n,r,!1))},"evaluateConditionExpression"),Se=f(e=>{if(e[0]!=="(")return-1;let t=0,r,n=-1;for(const i of e){if(n+=1,r){i===r&&(r=void 0);continue}if(i==='"'||i==="'"){r=i;continue}if(i==="(")t+=1;else if(i===")"&&(t-=1,t===0))return n}return-1},"matchingParen"),E=f((e,t)=>{let r="";for(const n of e){if(n.type==="text"){r+=n.value;continue}if(n.type==="expr"){r+=Ee(B(n.expression,t.scope,n.line,t.filename));continue}if(n.type==="if"){const i=x(n.condition,t.scope,t.filename,n.line)?n.consequent:n.alternate??[];r+=E(i,t);continue}if(n.type==="for"){const i=V(n.collection,t.scope,n.line,t.filename,!1);if(i==null)continue;if(!Array.isArray(i))throw new TypeError(`${t.filename}:${n.line}: {% for %} expected an array, got ${typeof i}`);for(const s of i){const a={...t.scope,[n.binding]:s};r+=E(n.body,{...t,scope:a})}continue}if(n.type==="include"){const i=t.partials?.get(n.name);if(!i)throw new Error(`${t.filename}:${n.line}: Partial "${n.name}" not found. Available: ${[...t.partials?.keys()??[]].join(", ")||"(none)"}`);const s=t.includeStack??new Set;if(s.has(n.name)){const a=[...s,n.name].join(" → ");throw new Error(`${t.filename}:${n.line}: Circular partial include detected: ${a}`)}s.add(n.name);try{r+=E(i,{...t,filename:`<partial:${n.name}>`,includeStack:s})}finally{s.delete(n.name)}}}return r},"renderNodes"),_e=f((e,t)=>G(U(e),t),"parseTemplate");f((e,t)=>E(e,t),"renderAst");const _=f((e,t)=>E(G(U(e),t.filename),t),"renderTemplate");var Ce=Object.defineProperty,y=v((e,t)=>Ce(e,"name",{value:t,configurable:!0}),"s");const P="template.yml",Te=".raw",We=new Set([".cjs",".css",".env",".gitattributes",".gitignore",".graphql",".html",".ini",".js",".json",".json5",".jsonc",".jsx",".lock",".md",".mdx",".mjs",".prettierrc",".raw",".rs",".scss",".sh",".sql",".svg",".tera",".toml",".ts",".tsx",".twig",".txt",".vue",".xml",".yaml",".yml"]),Ae=new Set(["Brewfile","CHANGELOG","CODEOWNERS","CONTRIBUTING","COPYING","Dockerfile","Gemfile","LICENCE","LICENSE","Makefile","NOTICE","Procfile","Rakefile","README","VERSION"]),Pe=y(e=>{const t=Math.max(e.lastIndexOf("/"),e.lastIndexOf("\\")),r=t===-1?e:e.slice(t+1),n=r.lastIndexOf(".");return n===-1||n===0?"":r.slice(n).toLowerCase()},"lastDot"),Y=y(e=>{const t=Math.max(e.lastIndexOf("/"),e.lastIndexOf("\\"));return t===-1?e:e.slice(t+1)},"basename"),Fe=y(e=>{const t=Pe(e);if(t!=="")return We.has(t);const r=Y(e);return!!Ae.has(r)},"isLikelyText"),Me=y(e=>{const t={default:e.default,internal:e.internal,order:e.order,prompt:e.prompt,required:e.required};switch(e.type){case"array":return{...t,type:"array"};case"boolean":return{...t,default:typeof t.default=="boolean"?t.default:void 0,type:"boolean"};case"enum":return{...t,multiple:e.multiple,type:"enum",values:e.values??[]};case"number":return{...t,type:"number"};case"string":return{...t,type:"string"};default:throw new Error(`Unsupported variable type "${String(e.type)}"`)}},"yamlVariableToVariable"),Re=y(e=>e.replaceAll("\\","/").replace(/^\.\//,"").replaceAll(/\/+/g,"/"),"normalizeDestinationPath"),Ie=y((e,t,r)=>{const n=t.split("/").filter(Boolean);if(n.length===0)throw new Error("Empty destination path for value");let i=e;for(let s=0;s<n.length-1;s+=1){const a=n[s],o=i[a];if(o===void 0){const l={};i[a]=l,i=l}else if(typeof o=="object"&&!Buffer.isBuffer(o))i=o;else throw new TypeError(`Path conflict: "${n.slice(0,s+1).join("/")}" is both a file and a directory`)}i[n.at(-1)]=r},"flattenFiles"),F=y((e,t,r)=>{if(typeof e!="string")return Ne(e);const n=e.includes("{{")||e.includes("{%")?_(e,{filename:`${r}#frontmatter`,scope:t}):e;return x(n,t,`${r}#frontmatter`,1)},"evaluateGate"),Ne=y(e=>e==null||e===!1||e===0||e===""?!1:Array.isArray(e)?e.length>0:typeof e=="string"?e!=="false"&&e!=="0":!0,"truthyValue"),De=y((e,t)=>{const r=R(e,P),n=X(r);if(!n||typeof n!="object")throw new Error(`${r}: must contain a YAML mapping`);const i={};if(n.variables)for(const[l,c]of Object.entries(n.variables))i[l]=Me(c);const s=new Map,a=[];for(const l of J(e,{includeDirs:!1,includeSymlinks:!1})){if(l.path===r)continue;const c=M(e,l.path).replaceAll("\\","/");if(c===P)continue;if(ye(c)){const u=k(l.path),g=_e(u,c);for(const p of Le(c))s.has(p)&&s.get(p)!==g&&console.warn(`warn: partial name "${p}" is declared by multiple files — last one wins. Use distinct names or fully-qualified includes.`),s.set(p,g);continue}if(c.endsWith(Te)){const u=k(l.path);a.push({binary:null,isRaw:!0,rawText:u,relativePath:c});continue}if(Fe(c)){const u=k(l.path);a.push({binary:null,isRaw:!1,rawText:u,relativePath:c});continue}const m=k(l.path,{buffer:!0});a.push({binary:m,isRaw:!1,rawText:null,relativePath:c})}const o=y(l=>{const c={...l.builtins,...l.options},m={},u={};for(const p of a){const w=p.relativePath;let O,C,T=!1;if(p.binary)O=p.binary;else if(p.isRaw)O=p.rawText??"";else{const K=p.rawText??"",b=we(K,z=>Z(z));if(b.frontmatter){if(b.frontmatter.skip!==void 0&&F(b.frontmatter.skip,c,w)||b.frontmatter.if!==void 0&&!F(b.frontmatter.if,c,w))continue;typeof b.frontmatter.to=="string"&&(C=_(b.frontmatter.to,{filename:`${w}#frontmatter.to`,partials:s,scope:c})),b.frontmatter.force===!0&&(T=!0)}O=_(b.body,{filename:w,partials:s,scope:c})}const W=Re(C??de(he(w),c));Ie(m,W,O),T&&(u[W]={force:!0})}const g={files:m};return Object.keys(u).length>0&&(g.filesMeta=u),g},"produce");return{about:{description:n.description??`Moon-format template at ${e}`,name:n.title??t},destination:n.destination,options:i,produce:o}},"loadMoonTemplate"),Le=y(e=>{const t=q(e),r=new Set;r.add(t);const n=Y(t);if(r.add(n),n.startsWith("_")){r.add(n.replace(/^_+/,""));const i=t.slice(0,t.length-n.length);r.add(`${i}${n.replace(/^_+/,"")}`)}return[...r]},"partialKeys");export{De as loadMoonTemplate};

package/dist/packem_chunks/loader.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var o=(t,e)=>n(t,"name",{value:e,configurable:!0});import{dirname as u}from"@visulima/path";import{createJiti as l}from"jiti";var i=Object.defineProperty,a=o((t,e)=>i(t,"name",{value:e,configurable:!0}),"r");const p=a((t,e)=>{if(!e||typeof e!="object")throw new TypeError(`${t}: default export must be an object (got ${e===null?"null":typeof e}). Use createTemplate({ ... }).`);const r=e;if(typeof r.about!="object"||r.about===null)throw new TypeError(`${t}: default export missing required "about" object`);if(typeof r.produce!="function")throw new TypeError(`${t}: default export missing required "produce" function`);return e},"validateTemplateExport"),d=a(async t=>{const e=await l(u(t),{fsCache:!1,moduleCache:!1}).import(t,{default:!0,try:!0})??null;return p(t,e)},"loadNativeTemplate");export{d as loadNativeTemplate};

package/dist/packem_shared/otelPlugin-CJLkguJ8.js

@@ -0,0 +1 @@
+import{otelPlugin as l}from"../config.js";export{l as otelPlugin};

package/dist/plugins/otel.d.ts

@@ -0,0 +1,63 @@
+import type { Task } from "@visulima/task-runner";
+import type { VisPlugin } from "../hooks.d.ts";
+/**
+ * Minimal OTel-shaped span. Deliberately structural so users can pass
+ * an `@opentelemetry/api` Tracer, an `@opentelemetry/sdk-node` one, or
+ * a custom implementation without the plugin depending on any
+ * particular OTel package.
+ */
+export interface OtelSpan {
+    end: () => void;
+    recordException?: (error: unknown) => void;
+    setAttribute?: (key: string, value: boolean | number | string) => void;
+    setStatus?: (status: {
+        code: number;
+        message?: string;
+    }) => void;
+}
+/**
+ * Minimal Tracer contract. Accepts the real
+ * `@opentelemetry/api`'s `Tracer.startSpan(name, options?)` shape —
+ * the plugin only calls the two methods it strictly needs.
+ */
+export interface OtelTracer {
+    startSpan: (name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }) => OtelSpan;
+}
+export interface OtelPluginOptions {
+    /**
+     * Rename incoming `project:target` IDs before they become OTel
+     * span names. Defaults to passing the id through unchanged.
+     */
+    renameSpan?: (task: Task) => string;
+    /** Tracer used to emit spans. Required — pass the one from `@opentelemetry/api`'s `trace.getTracer("vis")`. */
+    tracer: OtelTracer;
+}
+/**
+ * Reference plugin that maps vis hook lifecycle events to OTel spans.
+ *
+ * Emits:
+ * - one **root span** named `vis.run` spanning `run:before` → `run:after`
+ * - one **child span** per task spanning `task:before` → `task:after`
+ *   with attributes `vis.task.id`, `vis.task.project`, `vis.task.target`,
+ *   `vis.task.cache_status`, `vis.task.exit_code`
+ * - `task:failure` sets span status to ERROR and records the exit code
+ *
+ * Streaming stdout/stderr events are intentionally **not** emitted as
+ * span events — high-frequency chunks would blow up OTel backends. Use
+ * a log exporter if you need stream-level visibility.
+ * @example
+ * ```ts
+ * import { trace } from "@opentelemetry/api";
+ * import { defineConfig } from "@visulima/vis/config";
+ * import { otelPlugin } from "@visulima/vis/plugins/otel";
+ *
+ * const tracer = trace.getTracer("vis", "1.0.0");
+ *
+ * export default defineConfig({
+ *     plugins: [otelPlugin({ tracer })],
+ * });
+ * ```
+ */
+export declare const otelPlugin: (options: OtelPluginOptions) => VisPlugin;

package/dist/pm-runner.d.ts

@@ -2,7 +2,7 @@
  * Shared helper for executing package manager commands via native Rust bindings.
  * Falls back to JS-based detection when native bindings are unavailable.
  */
-import type { AddOptions, DlxOptions, ExecOptions, InstallOptions, OutdatedOptions, RemoveOptions, WhyOptions } from "./native-binding.d.ts";
+import type { AddOptions, DlxOptions, ExecOptions, InstallOptions, OutdatedOptions, RemoveOptions, ResolvedCommand, WhyOptions } from "./native-binding.d.ts";
 interface PmInfo {
     name: "bun" | "npm" | "pnpm" | "yarn";
     version: string;
@@ -14,10 +14,31 @@ declare const runRemove: (pm: PmInfo, options: RemoveOptions, cwd: string, logge
 declare const runDedupe: (pm: PmInfo, check: boolean, cwd: string, logger: Console) => number;
 declare const runWhy: (pm: PmInfo, options: WhyOptions, cwd: string, logger: Console) => number;
 declare const runOutdated: (pm: PmInfo, options: OutdatedOptions, cwd: string, logger: Console) => number;
+interface InfoOptions {
+    fields: string[];
+    json: boolean;
+    package: string;
+}
+/**
+ * Resolves a registry metadata lookup to a runnable command. Built in TS
+ * rather than the Rust resolver because bun needs `pm view` (two-word
+ * subcommand) and yarn berry needs `yarn npm info` — both shapes the existing
+ * `resolve_pm_command` view branch gets wrong.
+ *
+ * Pure function — exported for unit testing.
+ */
+declare const resolveInfo: (pm: PmInfo, options: InfoOptions) => ResolvedCommand;
+declare const runInfo: (pm: PmInfo, options: InfoOptions, cwd: string, logger: Console) => number;
+/**
+ * Resolves and runs a PM `link` operation. Passes `pm.version` to the native
+ * resolver so it can warn about pnpm v11 restrictions (arg-less link and
+ * global-store name resolution were removed). `target` is `null` for arg-less
+ * link, or a package name / path string.
+ */
 declare const runLink: (pm: PmInfo, target: string | null, cwd: string, logger: Console) => number;
 declare const runUnlink: (pm: PmInfo, packages: string[], recursive: boolean, cwd: string, logger: Console) => number;
 declare const runDlx: (pm: PmInfo, options: DlxOptions, cwd: string, logger: Console) => number;
 declare const runExec: (pm: PmInfo, options: ExecOptions, cwd: string, logger: Console) => number;
 declare const runPmSubcommand: (pm: PmInfo, subcommand: string, args: string[], cwd: string, logger: Console) => number;
-export type { PmInfo };
-export { detectPm, runAdd, runDedupe, runDlx, runExec, runInstall, runLink, runOutdated, runPmSubcommand, runRemove, runUnlink, runWhy };
+export type { InfoOptions, PmInfo };
+export { detectPm, resolveInfo, runAdd, runDedupe, runDlx, runExec, runInfo, runInstall, runLink, runOutdated, runPmSubcommand, runRemove, runUnlink, runWhy };

package/dist/run-report.d.ts

@@ -0,0 +1,40 @@
+import type { TaskResults } from "@visulima/task-runner";
+/**
+ * Formats a compact one-line timing summary for display after a run.
+ * @param results Task execution results.
+ * @param durationMs Total wall-clock duration in milliseconds.
+ * @returns A formatted summary string, e.g. "3 succeeded · 1 cached · 0 failed · 2.4s"
+ */
+export declare const formatTimingSummary: (results: TaskResults, durationMs: number) => string;
+/**
+ * Shape of a persisted run summary — only the fields this module + the
+ * flakiness analyzer consume. Kept narrow so both consumers can share
+ * one loader without pulling in the full `RunSummary` type from
+ * task-runner.
+ */
+export interface LoadedRunSummary {
+    [key: string]: unknown;
+    duration?: number;
+    startTime?: string;
+    tasks?: unknown[];
+}
+/**
+ * Reads every `.task-runner/runs/*.json` once and returns the parsed
+ * array. Callers that need to iterate historical runs (timing average,
+ * flakiness analysis) should call this once per command and feed the
+ * result into the downstream helpers rather than re-reading the
+ * directory multiple times.
+ *
+ * Corrupt or unreadable files are skipped silently — a single bad
+ * summary shouldn't take down the whole analysis.
+ */
+export declare const loadRunSummaries: (workspaceRoot: string) => LoadedRunSummary[];
+/**
+ * Loads durations from historical run summaries and computes the
+ * average. Returns the comparison string or `undefined` if no history.
+ *
+ * Pass `summaries` (from {@link loadRunSummaries}) when the caller
+ * has already loaded the history for another purpose (e.g. flakiness
+ * analysis on a failing run) to avoid re-reading the same files.
+ */
+export declare const compareDuration: (workspaceRoot: string, currentDurationMs: number, summaries?: LoadedRunSummary[]) => string | undefined;

package/dist/runtime-check.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime-version mismatch finding. vis doesn't manage runtimes directly,
+ * but it can warn when the currently running Node/Bun/Deno doesn't match
+ * whatever the repo has declared — usually a sign the user forgot to
+ * switch runtimes for this workspace.
+ */
+export interface RuntimeFinding {
+    actual: string;
+    expected: string;
+    kind: "node" | "packageManager";
+    message: string;
+    severity: "error" | "warning";
+}
+/**
+ * Evaluates a minimal subset of semver ranges: `>=X`, `X.Y`, `X.Y.Z`,
+ * and compound `>=X <Y`. Returns true if `actual` satisfies the range.
+ * Falls back to "true" for unrecognised syntax rather than false so we
+ * don't spam warnings on exotic ranges.
+ */
+export declare const satisfiesRange: (actual: string, range: string) => boolean;
+/**
+ * Checks `engines.node`, `.nvmrc`, `.node-version`, and `packageManager`
+ * against the running process.
+ * @param workspaceRoot Absolute path to the workspace root.
+ * @returns Findings; an empty array means everything matches.
+ */
+export declare const checkRuntimeVersions: (workspaceRoot: string) => RuntimeFinding[];