@visulima/vis 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/packem_chunks/handler37.js

@@ -0,0 +1,762 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+import { dim, bold, cyan } from '@visulima/colorize';
+import { join, dirname, relative, isAbsolute, sep, resolve } from '@visulima/path';
+const {
+  fileURLToPath
+} = __cjs_getBuiltinModule("node:url");
+import { isAccessibleSync, walkSync, ensureDirSync, writeFileSync } from '@visulima/fs';
+const {
+  createInterface
+} = __cjs_getBuiltinModule("node:readline");
+const {
+  mkdtempSync,
+  rmSync
+} = __cjs_getBuiltinModule("node:fs");
+const {
+  tmpdir
+} = __cjs_getBuiltinModule("node:os");
+import { downloadTemplate } from 'giget';
+import { p as pail } from './bin.js';
+const {
+  spawnSync
+} = __cjs_getBuiltinModule("node:child_process");
+
+const NATIVE_EXTENSIONS = [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
+const TEMPLATE_YML = "template.yml";
+const BLOCKED_BASE_SUFFIXES = [".d", ".test", ".spec", ".config", ".bench", ".stories"];
+const BLOCKED_FULL_EXTENSIONS = [".d.ts", ".d.mts", ".d.cts", ".js.map", ".mjs.map", ".cjs.map", ".ts.map"];
+const stripExtension = (filename) => {
+  for (const ext of NATIVE_EXTENSIONS) {
+    if (filename.endsWith(ext)) {
+      return filename.slice(0, -ext.length);
+    }
+  }
+  return filename;
+};
+const isNativeFile = (filename) => {
+  if (BLOCKED_FULL_EXTENSIONS.some((ext) => filename.endsWith(ext))) {
+    return false;
+  }
+  if (!NATIVE_EXTENSIONS.some((ext) => filename.endsWith(ext))) {
+    return false;
+  }
+  const base = stripExtension(filename);
+  return !BLOCKED_BASE_SUFFIXES.some((suffix) => base.endsWith(suffix));
+};
+const scanNativeDirectory = (directory, source) => {
+  const results = [];
+  if (!isAccessibleSync(directory)) {
+    return results;
+  }
+  for (const entry of walkSync(directory, { includeDirs: false, includeSymlinks: false, maxDepth: 1 })) {
+    if (!isNativeFile(entry.name)) {
+      continue;
+    }
+    const name = stripExtension(entry.name);
+    results.push({
+      // Lazy loader — module is loaded only when the user picks the template.
+      load: () => loadNativeFromPath(entry.path),
+      name,
+      path: entry.path,
+      source
+    });
+  }
+  return results;
+};
+const scanMoonDirectory = (directory, source) => {
+  const results = [];
+  if (!isAccessibleSync(directory)) {
+    return results;
+  }
+  for (const entry of walkSync(directory, { includeFiles: false, includeSymlinks: false, maxDepth: 1 })) {
+    if (entry.path === directory) {
+      continue;
+    }
+    const yamlPath = join(entry.path, TEMPLATE_YML);
+    if (!isAccessibleSync(yamlPath)) {
+      continue;
+    }
+    results.push({
+      load: () => loadMoonFromPath(entry.path, entry.name),
+      name: entry.name,
+      path: entry.path,
+      source
+    });
+  }
+  return results;
+};
+const resolveBuiltinTemplatesDirectory = () => {
+  try {
+    const here = fileURLToPath(import.meta.url);
+    const candidate = join(dirname(here), "..", "..", "templates");
+    return isAccessibleSync(candidate) ? candidate : void 0;
+  } catch {
+    return void 0;
+  }
+};
+const discoverTemplates = (options) => {
+  const { extraDirectories = [], onWarning, workspaceRoot } = options;
+  const results = [];
+  results.push(...scanNativeDirectory(join(workspaceRoot, ".vis", "templates"), "native"));
+  results.push(...scanMoonDirectory(join(workspaceRoot, ".vis", "templates"), "moon"));
+  results.push(...scanMoonDirectory(join(workspaceRoot, ".moon", "templates"), "moon"));
+  for (const directory of extraDirectories) {
+    results.push(...scanMoonDirectory(directory, "config"));
+    results.push(...scanNativeDirectory(directory, "config"));
+  }
+  const builtinDirectory = resolveBuiltinTemplatesDirectory();
+  if (builtinDirectory) {
+    results.push(...scanMoonDirectory(builtinDirectory, "builtin"));
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const template of results) {
+    const existing = seen.get(template.name);
+    if (!existing) {
+      seen.set(template.name, template);
+      continue;
+    }
+    if (onWarning) {
+      onWarning(
+        `Template "${template.name}" exists in multiple sources — using ${existing.source} (${existing.path}), ignoring ${template.source} (${template.path}).`
+      );
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+};
+const loadNativeFromPath = async (path) => {
+  const { loadNativeTemplate } = await import('./loader.js');
+  return loadNativeTemplate(path);
+};
+const loadMoonFromPath = async (path, name) => {
+  const { loadMoonTemplate } = await import('./index.js');
+  return loadMoonTemplate(path, name);
+};
+
+const ask = (rl, question) => new Promise((resolve) => {
+  rl.question(question, (answer) => {
+    resolve(answer.trim());
+  });
+});
+const confirm = async (rl, question, defaultYes) => {
+  const hint = defaultYes ? "[Y/n]" : "[y/N]";
+  const answer = await ask(rl, `  ${question} ${dim(hint)} `);
+  if (answer === "") {
+    return defaultYes;
+  }
+  return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
+};
+const selectOne = async (rl, question, choices, defaultValue) => {
+  process.stderr.write(`  ${question}
+`);
+  for (const [index, choice] of choices.entries()) {
+    const prefix = bold(cyan(`  ${String(index + 1)}.`));
+    const star = choice === defaultValue ? dim(" (default)") : "";
+    process.stderr.write(`${prefix} ${choice}${star}
+`);
+  }
+  while (true) {
+    const answer = await ask(rl, `
+  ${dim(`Enter choice (1-${String(choices.length)}):`)} `);
+    if (answer === "" && defaultValue !== void 0) {
+      return defaultValue;
+    }
+    const number_ = Number.parseInt(answer, 10);
+    if (Number.isInteger(number_) && number_ >= 1 && number_ <= choices.length) {
+      return choices[number_ - 1];
+    }
+    const match = choices.find((c) => c === answer);
+    if (match) {
+      return match;
+    }
+    process.stderr.write(`  ${dim("Invalid choice. Try again.")}
+`);
+  }
+};
+const selectMany = async (rl, question, choices, defaultValues) => {
+  process.stderr.write(`  ${question} ${dim("(comma-separated numbers)")}
+`);
+  for (const [index, choice] of choices.entries()) {
+    const prefix = bold(cyan(`  ${String(index + 1)}.`));
+    const star = defaultValues.includes(choice) ? dim(" (default)") : "";
+    process.stderr.write(`${prefix} ${choice}${star}
+`);
+  }
+  while (true) {
+    const answer = await ask(rl, `
+  ${dim(`Enter choices:`)} `);
+    if (answer === "" && defaultValues.length > 0) {
+      return defaultValues;
+    }
+    const indices = answer.split(",").map((part) => Number.parseInt(part.trim(), 10)).filter((n) => Number.isInteger(n) && n >= 1 && n <= choices.length);
+    if (indices.length > 0) {
+      return indices.map((index) => choices[index - 1]);
+    }
+    process.stderr.write(`  ${dim("Invalid choice. Try again.")}
+`);
+  }
+};
+const promptText = (label) => `  ${dim(`${label}:`)} `;
+const variableLabel = (name, variable) => variable.prompt ?? name;
+const sortVariables = (variables) => Object.entries(variables).sort(([nameA, a], [nameB, b]) => {
+  const orderA = a.order ?? 0;
+  const orderB = b.order ?? 0;
+  if (orderA !== orderB) {
+    return orderA - orderB;
+  }
+  return nameA.localeCompare(nameB);
+});
+const parseValue = (variable, raw) => {
+  switch (variable.type) {
+    case "array": {
+      return raw.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+    case "boolean": {
+      return raw === "true" || raw === "1" || raw === "yes" || raw === "y";
+    }
+    case "enum": {
+      if (variable.multiple) {
+        return raw.split(",").map((s) => s.trim()).filter(Boolean);
+      }
+      return raw;
+    }
+    case "number": {
+      const parsed = Number(raw);
+      if (Number.isNaN(parsed)) {
+        throw new TypeError(`Expected a number, got "${raw}"`);
+      }
+      return parsed;
+    }
+    default: {
+      return raw;
+    }
+  }
+};
+const validateValue = (name, variable, value) => {
+  if (variable.type === "enum") {
+    const values = Array.isArray(value) ? value : [value];
+    for (const candidate of values) {
+      if (typeof candidate !== "string" || !variable.values.includes(candidate)) {
+        throw new Error(`Variable "${name}" must be one of: ${variable.values.join(", ")} (got "${String(candidate)}")`);
+      }
+    }
+  }
+};
+const collectOptions = async (collectOptionsArguments) => {
+  const { defaults, interactive, overrides, variables } = collectOptionsArguments;
+  const result = {};
+  const rl = interactive ? createInterface({ input: process.stdin, output: process.stderr }) : null;
+  try {
+    for (const [name, variable] of sortVariables(variables)) {
+      if (Object.hasOwn(overrides, name)) {
+        const value2 = parseValue(variable, overrides[name] ?? "");
+        validateValue(name, variable, value2);
+        result[name] = value2;
+        continue;
+      }
+      if (defaults || !interactive || variable.internal) {
+        if (variable.default !== void 0) {
+          validateValue(name, variable, variable.default);
+          result[name] = variable.default;
+          continue;
+        }
+        if (variable.required) {
+          throw new Error(`Required variable "${name}" not provided. Pass --${name}=<value> or remove --defaults.`);
+        }
+        continue;
+      }
+      const label = variableLabel(name, variable);
+      let value;
+      if (variable.type === "boolean") {
+        value = await confirm(rl, label, Boolean(variable.default ?? false));
+      } else if (variable.type === "enum") {
+        if (variable.multiple) {
+          const defaultValues = Array.isArray(variable.default) ? variable.default : [];
+          value = await selectMany(rl, label, variable.values, defaultValues);
+        } else {
+          const defaultValue = typeof variable.default === "string" ? variable.default : void 0;
+          value = await selectOne(rl, label, variable.values, defaultValue);
+        }
+      } else {
+        const defaultHint = variable.default === void 0 ? "" : ` (${String(variable.default)})`;
+        const raw = await ask(rl, promptText(`${label}${defaultHint}`));
+        if (raw === "" && variable.default !== void 0) {
+          value = variable.default;
+        } else if (raw === "") {
+          if (variable.required) {
+            throw new Error(`Variable "${name}" is required`);
+          }
+          continue;
+        } else {
+          value = parseValue(variable, raw);
+        }
+      }
+      validateValue(name, variable, value);
+      result[name] = value;
+    }
+    return result;
+  } finally {
+    rl?.close();
+  }
+};
+
+const REMOTE_PROTOCOLS = ["git://", "npm://", "https://", "github:", "gitlab:", "bitbucket:", "sourcehut:"];
+const isRemoteSource = (input) => REMOTE_PROTOCOLS.some((protocol) => input.startsWith(protocol));
+const fetchRemoteTemplate = async (source, options = {}) => {
+  const ownDirectory = options.targetDirectory === void 0;
+  const directory = options.targetDirectory ?? mkdtempSync(join(tmpdir(), "vis-generate-"));
+  const cleanup = () => {
+    if (!ownDirectory) {
+      return;
+    }
+    try {
+      rmSync(directory, { force: true, recursive: true });
+    } catch {
+    }
+  };
+  pail.info(`Downloading ${source}…`);
+  try {
+    const result = await downloadTemplate(source, {
+      auth: options.auth || process.env.GIGET_AUTH || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || void 0,
+      dir: directory,
+      force: true,
+      preferOffline: options.preferOffline
+    });
+    return { cleanup, directory: result.dir };
+  } catch (error) {
+    cleanup();
+    const message = error instanceof Error ? error.message : String(error);
+    pail.warn(`Failed to download template: ${message}`);
+    throw error;
+  }
+};
+
+const flattenTree = (tree, prefix = "") => {
+  const result = [];
+  for (const [key, value] of Object.entries(tree)) {
+    const path = prefix ? `${prefix}/${key}` : key;
+    if (typeof value === "string" || Buffer.isBuffer(value)) {
+      result.push({ content: value, path });
+    } else if (value && typeof value === "object") {
+      result.push(...flattenTree(value, path));
+    }
+  }
+  return result;
+};
+const formatSize = (bytes) => {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+const safeJoinDestination = (destination, relPath) => {
+  if (isAbsolute(relPath)) {
+    throw new Error(`Refusing to write outside destination: template produced absolute path "${relPath}".`);
+  }
+  const target = join(destination, relPath);
+  const rel = relative(destination, target);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`Refusing to write outside destination: "${relPath}" resolves to "${target}" which escapes "${destination}".`);
+  }
+  return target;
+};
+const writeOne = (destinationPath, content) => {
+  ensureDirSync(dirname(destinationPath));
+  writeFileSync(destinationPath, content);
+};
+const runScript = (script, cwd, silent = false) => {
+  const commands = typeof script === "string" ? [script] : script.commands;
+  const isSilent = typeof script === "string" ? silent : script.silent ?? silent;
+  for (const command of commands) {
+    if (!isSilent) {
+      pail.info(`$ ${command}`);
+    }
+    const result = spawnSync(command, {
+      cwd,
+      shell: true,
+      stdio: isSilent ? "ignore" : "inherit"
+    });
+    if (result.status !== 0) {
+      pail.warn(`Script failed (exit ${String(result.status)}): ${command}`);
+      return false;
+    }
+  }
+  return true;
+};
+const groupByPhase = (scripts) => {
+  const phases = /* @__PURE__ */ new Map();
+  for (const script of scripts) {
+    const phase = typeof script === "string" ? 0 : script.phase ?? 0;
+    const bucket = phases.get(phase);
+    if (bucket) {
+      bucket.push(script);
+    } else {
+      phases.set(phase, [script]);
+    }
+  }
+  return [...phases.entries()].sort(([a], [b]) => a - b);
+};
+const runTemplate = async (template, options) => {
+  const builtins = {
+    dest_dir: options.destination,
+    dest_rel_dir: relative(options.workspaceRoot, options.destination) || ".",
+    working_dir: options.cwd,
+    workspace_root: options.workspaceRoot
+  };
+  const context = {
+    builtins,
+    options: options.options
+  };
+  const creation = await template.produce(context);
+  const files = creation.files ? flattenTree(creation.files) : [];
+  const filesMeta = creation.filesMeta ?? {};
+  const plans = [];
+  for (const file of files) {
+    const target = safeJoinDestination(options.destination, file.path);
+    plans.push({ file, meta: filesMeta[file.path] ?? {}, target });
+  }
+  if (options.dryRun) {
+    pail.info(`${bold(cyan("Plan"))} ${dim("(dry-run, no files written)")}`);
+    for (const plan of plans) {
+      const size = Buffer.isBuffer(plan.file.content) ? plan.file.content.length : Buffer.byteLength(plan.file.content, "utf8");
+      process.stderr.write(`  ${dim("write")} ${plan.file.path} ${dim(`(${formatSize(size)})`)}
+`);
+    }
+  } else {
+    ensureDirSync(options.destination);
+    let written = 0;
+    let skipped = 0;
+    for (const plan of plans) {
+      const { file, meta, target } = plan;
+      const exists = isAccessibleSync(target);
+      const effectiveForce = options.force || meta.force === true;
+      if (exists && !effectiveForce) {
+        pail.warn(`Skipped existing file: ${file.path} (use --force or set frontmatter force: true to overwrite)`);
+        skipped += 1;
+        continue;
+      }
+      writeOne(target, file.content);
+      written += 1;
+    }
+    pail.success(`Wrote ${String(written)} file${written === 1 ? "" : "s"}${skipped > 0 ? `, skipped ${String(skipped)}` : ""}`);
+  }
+  if (!options.dryRun && !options.skipScripts && creation.scripts && creation.scripts.length > 0) {
+    const phases = groupByPhase(creation.scripts);
+    pail.info(
+      `Running ${String(creation.scripts.length)} script${creation.scripts.length === 1 ? "" : "s"} across ${String(phases.length)} phase${phases.length === 1 ? "" : "s"}…`
+    );
+    for (const [, scripts] of phases) {
+      const results = await Promise.all(scripts.map((script) => Promise.resolve(runScript(script, options.destination))));
+      if (results.includes(false)) {
+        throw new Error("Script failed — aborting.");
+      }
+    }
+  }
+  if (creation.suggestions && creation.suggestions.length > 0) {
+    process.stderr.write("\n");
+    pail.notice("Next steps:");
+    for (const suggestion of creation.suggestions) {
+      process.stderr.write(`  ${dim("•")} ${suggestion}
+`);
+    }
+  }
+};
+
+const toListEntry = async (template) => {
+  let description;
+  try {
+    const loaded = await template.load();
+    description = loaded.about?.description;
+  } catch {
+  }
+  return { description, name: template.name, path: template.path, source: template.source };
+};
+const summarizeVariable = (name, variable) => {
+  const summary = {
+    default: variable.default,
+    name,
+    order: variable.order,
+    prompt: variable.prompt,
+    required: variable.required,
+    type: variable.type
+  };
+  if (variable.type === "enum") {
+    summary.multiple = variable.multiple;
+    summary.values = variable.values;
+  }
+  return summary;
+};
+const describeTemplate = async (discovered) => {
+  const loaded = await discovered.load();
+  const variables = Object.entries(loaded.options ?? {}).sort(([nameA, a], [nameB, b]) => {
+    const orderA = a.order ?? 0;
+    const orderB = b.order ?? 0;
+    return orderA === orderB ? nameA.localeCompare(nameB) : orderA - orderB;
+  }).map(([name, variable]) => summarizeVariable(name, variable));
+  return {
+    description: loaded.about?.description ?? "",
+    destination: loaded.destination,
+    name: discovered.name,
+    path: discovered.path,
+    source: discovered.source,
+    variables
+  };
+};
+const printList = (templates) => {
+  if (templates.length === 0) {
+    pail.info("No templates found.");
+    pail.notice("Create one at .vis/templates/<name>.ts (programmatic) or .vis/templates/<name>/ (moon-format with template.yml).");
+    return;
+  }
+  pail.info("Available templates:");
+  for (const template of templates) {
+    const tag = dim(`(${template.source})`);
+    process.stderr.write(`  ${bold(cyan(template.name))} ${tag}
+`);
+  }
+};
+const parsePassthroughOverrides = (extraArguments) => {
+  const overrides = {};
+  const remaining = [];
+  for (const argument of extraArguments) {
+    if (!argument.startsWith("--")) {
+      remaining.push(argument);
+      continue;
+    }
+    const equalsIndex = argument.indexOf("=");
+    if (equalsIndex === -1) {
+      const key2 = argument.slice(2);
+      if (key2.startsWith("no-")) {
+        overrides[key2.slice(3)] = "false";
+      } else {
+        overrides[key2] = "true";
+      }
+      continue;
+    }
+    const key = argument.slice(2, equalsIndex);
+    const value = argument.slice(equalsIndex + 1);
+    overrides[key] = value;
+  }
+  return { overrides, remaining };
+};
+const pickInteractive = async (templates) => {
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    process.stderr.write(`  ${bold(cyan("vis generate"))} ${dim("— pick a template")}
+
+`);
+    for (const [index, template] of templates.entries()) {
+      const prefix = bold(cyan(`  ${String(index + 1)}.`));
+      process.stderr.write(`${prefix} ${template.name} ${dim(`(${template.source})`)}
+`);
+    }
+    return new Promise((resolveValue, reject) => {
+      rl.question(`
+  ${dim(`Enter choice (1-${String(templates.length)}):`)} `, (answer) => {
+        const number_ = Number.parseInt(answer.trim(), 10);
+        if (Number.isInteger(number_) && number_ >= 1 && number_ <= templates.length) {
+          resolveValue(templates[number_ - 1].name);
+        } else {
+          reject(new Error("Invalid choice."));
+        }
+      });
+    });
+  } finally {
+    rl.close();
+  }
+};
+const execute = async ({ argument, options, rawUnknown, visConfig, workspaceRoot: wsRoot }) => {
+  const cwd = options.cwd || wsRoot || process.cwd();
+  const workspaceRoot = wsRoot ?? cwd;
+  const generatorConfig = visConfig?.generator;
+  const args = Array.isArray(argument) ? argument : argument ? [argument] : [];
+  if (options.list) {
+    const discovered = discoverTemplates({
+      extraDirectories: generatorConfig?.templates ?? [],
+      onWarning: (message) => {
+        pail.warn(message);
+      },
+      workspaceRoot
+    });
+    if (options.json) {
+      const entries = await Promise.all(discovered.map((t) => toListEntry(t)));
+      process.stdout.write(`${JSON.stringify(entries, null, 2)}
+`);
+      return;
+    }
+    printList(discovered);
+    return;
+  }
+  if (options.describe) {
+    const wanted = args[0];
+    if (!wanted) {
+      throw new Error("`--describe` requires a template name. Run `vis generate --list` to see available templates.");
+    }
+    const discovered = discoverTemplates({
+      extraDirectories: generatorConfig?.templates ?? [],
+      onWarning: (message) => {
+        pail.warn(message);
+      },
+      workspaceRoot
+    });
+    const match = discovered.find((t) => t.name === wanted);
+    if (!match) {
+      throw new Error(`Template "${wanted}" not found. Run \`vis generate --list\` to see available templates.`);
+    }
+    const described = await describeTemplate(match);
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(described, null, 2)}
+`);
+      return;
+    }
+    pail.info(`Template: ${bold(cyan(described.name))} ${dim(`(${described.source})`)}`);
+    if (described.description) {
+      pail.info(described.description);
+    }
+    if (described.destination) {
+      pail.info(`Destination: ${dim(described.destination)}`);
+    }
+    if (described.variables.length === 0) {
+      pail.info("No variables.");
+    } else {
+      pail.info("Variables:");
+      for (const variable of described.variables) {
+        const flags = [variable.type];
+        if (variable.required) flags.push("required");
+        if (variable.default !== void 0) flags.push(`default=${JSON.stringify(variable.default)}`);
+        if (variable.values) flags.push(`values=${variable.values.join("|")}`);
+        process.stderr.write(`  ${bold(cyan(variable.name))} ${dim(`(${flags.join(", ")})`)}
+`);
+      }
+    }
+    return;
+  }
+  let passthrough = [...rawUnknown ?? []];
+  if (passthrough.length === 0) {
+    const rawArgv = process.argv.slice(2);
+    const argvDashIndex = rawArgv.indexOf("--");
+    if (argvDashIndex !== -1) {
+      passthrough = rawArgv.slice(argvDashIndex + 1);
+    }
+  }
+  const legacyDashIndex = args.indexOf("--");
+  const legacyExtras = legacyDashIndex === -1 ? [] : args.slice(legacyDashIndex + 1);
+  const ownArgs = legacyDashIndex === -1 ? args : args.slice(0, legacyDashIndex);
+  const { overrides } = parsePassthroughOverrides([...legacyExtras, ...passthrough]);
+  let template;
+  let templateName;
+  let templateDestination;
+  const input = ownArgs[0];
+  let remoteCleanup;
+  if (input && isRemoteSource(input)) {
+    const fetched = await fetchRemoteTemplate(input, {
+      auth: generatorConfig?.auth,
+      preferOffline: Boolean(options.preferOffline) || generatorConfig?.preferOffline
+    });
+    remoteCleanup = fetched.cleanup;
+    try {
+      const discovered = discoverTemplates({ extraDirectories: [fetched.directory], workspaceRoot });
+      const remoteTemplate = discovered.find((t) => t.path.startsWith(fetched.directory));
+      if (!remoteTemplate) {
+        throw new Error(`Downloaded template at ${fetched.directory} contains no template.yml or *.ts entrypoint.`);
+      }
+      template = await remoteTemplate.load();
+      templateName = remoteTemplate.name;
+      templateDestination = template.destination;
+    } catch (error) {
+      remoteCleanup();
+      remoteCleanup = void 0;
+      throw error;
+    }
+  } else {
+    const discovered = discoverTemplates({
+      extraDirectories: generatorConfig?.templates ?? [],
+      onWarning: (message) => {
+        pail.warn(message);
+      },
+      workspaceRoot
+    });
+    if (discovered.length === 0) {
+      throw new Error("No templates found. Create one at .vis/templates/<name>.ts or .vis/templates/<name>/template.yml.");
+    }
+    let wanted;
+    if (input) {
+      wanted = input;
+    } else if (options.noInteractive || !process.stdin.isTTY) {
+      throw new Error("No template specified. Pass a template name (see `vis generate --list`) or run interactively in a terminal.");
+    } else {
+      wanted = await pickInteractive(discovered);
+    }
+    const match = discovered.find((t) => t.name === wanted);
+    if (!match) {
+      throw new Error(`Template "${wanted}" not found. Run 'vis generate --list' to see available templates.`);
+    }
+    template = await match.load();
+    templateName = match.name;
+    templateDestination = template.destination;
+  }
+  const toFlag = options.to;
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const useDefaults = Boolean(options.defaults);
+  const skipScripts = Boolean(options.skipScripts);
+  const isInteractive = !options.noInteractive && Boolean(process.stdin.isTTY) && !useDefaults;
+  let destinationInput;
+  if (toFlag) {
+    destinationInput = toFlag;
+  } else if (templateDestination) {
+    destinationInput = templateDestination;
+  } else {
+    destinationInput = ".";
+  }
+  const destination = isAbsolute(destinationInput) ? destinationInput : resolve(cwd, destinationInput);
+  pail.info(`Template: ${bold(cyan(templateName))}`);
+  pail.info(`Target:   ${dim(destination)}`);
+  process.stderr.write("\n");
+  const collectedOptions = await collectOptions({
+    defaults: useDefaults,
+    interactive: isInteractive,
+    overrides,
+    variables: template.options ?? {}
+  });
+  try {
+    await runTemplate(template, {
+      cwd,
+      destination,
+      dryRun,
+      force,
+      options: collectedOptions,
+      skipScripts,
+      workspaceRoot
+    });
+    if (!dryRun) {
+      process.stderr.write("\n");
+      pail.success(`Template '${templateName}' applied.`);
+    }
+  } finally {
+    remoteCleanup?.();
+  }
+};
+
+export { execute as default };