@uplift-beyond/upex 0.0.0-stage → 1.5.0

package/src/commands/completion.js

@@ -0,0 +1,75 @@
+/**
+ * completion.js -- Shell completion scripts + the hidden __names helper.
+ * Usage: upex completion [bash|zsh|fish|powershell]
+ *   e.g. eval "$(upex completion bash)"   (bash/zsh)
+ *        upex completion powershell | Out-String | Invoke-Expression
+ */
+
+import os from 'node:os';
+import { loadLinks } from '../store.js';
+import * as ui from '../ui.js';
+
+// SUBCOMMANDS comes from the registered commands, so new ones complete with no manual list.
+const scripts = (SUBCOMMANDS) => ({
+  bash: `_upex() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${SUBCOMMANDS} $(upex __names)" -- "$cur") )
+  else
+    COMPREPLY=( $(compgen -W "$(upex __names)" -- "$cur") )
+  fi
+}
+complete -F _upex upex`,
+
+  zsh: `_upex() {
+  local -a cmds names
+  cmds=(${SUBCOMMANDS})
+  names=(\${(f)"$(upex __names)"})
+  compadd -- $cmds $names
+}
+compdef _upex upex`,
+
+  fish: `complete -c upex -f -a "(upex __names)"
+complete -c upex -n "__fish_use_subcommand" -a "${SUBCOMMANDS}"`,
+
+  powershell: `Register-ArgumentCompleter -Native -CommandName upex -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $cmds = @('${SUBCOMMANDS.split(' ').join("','")}')
+  $names = @(upex __names)
+  ($cmds + $names) | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}`,
+});
+
+function detectShell() {
+  if (os.platform() === 'win32') return 'powershell';
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('fish')) return 'fish';
+  return 'bash';
+}
+
+export function registerCompletion(program) {
+  program
+    .command('__names', { hidden: true })
+    .description('(internal) Print all shortcut names for completion')
+    .action(() => {
+      process.stdout.write(Object.keys(loadLinks()).join('\n'));
+    });
+
+  program
+    .command('completion [shell]')
+    .description('Print a shell completion script (bash|zsh|fish|powershell)')
+    .summary('Print a shell completion script')
+    .action((shell) => {
+      const key = (shell || detectShell()).toLowerCase();
+      const names = program.createHelp().visibleCommands(program).flatMap(c => [c.name(), ...c.aliases()]);
+      const script = scripts(names.join(' '))[key === 'pwsh' ? 'powershell' : key];
+      if (!script) {
+        ui.error(`No completion for "${shell}". Supported: bash, zsh, fish, powershell`);
+        process.exit(1);
+      }
+      process.stdout.write(script + '\n');
+    });
+}

package/src/commands/copy.js

@@ -0,0 +1,51 @@
+/**
+ * copy.js -- Copy a shortcut's path to the clipboard.
+ * Usage: upex copy <name>
+ */
+
+import { loadLinks } from '../store.js';
+import { copyToClipboard } from '../launcher.js';
+import { resolveName, didYouMean } from '../fuzzy.js';
+import * as ui from '../ui.js';
+
+export function registerCopy(program) {
+  program
+    .command('copy <name>')
+    .description('Copy shortcut path to clipboard')
+    .action((name) => {
+      const links = loadLinks();
+      const resolved = resolveName(name, links);
+
+      if (!resolved) {
+        ui.error(`Shortcut not found: ${name}`);
+        const hint = didYouMean(name, Object.keys(links));
+        if (hint) ui.dim(hint);
+        process.exit(1);
+      }
+
+      const entry = links[resolved.name];
+      const targetPath = entry.path || entry.url;
+
+      if (!targetPath) {
+        ui.warn(`"${resolved.name}" is an app shortcut with no folder path.`);
+        if (entry.app) {
+          ui.dim(`App executable: ${entry.app}`);
+        }
+        process.exit(1);
+      }
+
+      try {
+        copyToClipboard(targetPath);
+      } catch (err) {
+        ui.error(`Failed to copy: ${err.message}`);
+        process.exit(1);
+      }
+
+      if (!resolved.exact) {
+        ui.dim(`matched "${name}" --> "${resolved.name}"`);
+      }
+
+      ui.success(`Copied: ${targetPath}`);
+    });
+}
+

package/src/commands/doctor.js

@@ -0,0 +1,130 @@
+/**
+ * doctor.js -- Check that upex is set up and healthy.
+ * Usage: upex doctor
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { loadLinks, loadConfig, loadWorkspaces, LINKS_FILE } from '../store.js';
+import { getAppMap, checkOpener, openerKey } from '../launcher.js';
+import { CMD_WRAPPER, findShimDir } from './setup.js';
+import { resolveTarget } from '../fuzzy.js';
+import * as ui from '../ui.js';
+
+const platform = os.platform();
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const readText = (f) => { try { return fs.readFileSync(f, 'utf-8'); } catch { return ''; } };
+
+// Shell profiles that could hold the cd wrapper or completion.
+function profileFiles() {
+  const home = os.homedir();
+  const files = [
+    path.join(home, '.bashrc'),
+    path.join(home, '.bash_profile'),
+    path.join(home, '.zshrc'),
+    path.join(home, '.config', 'fish', 'config.fish'),
+    path.join(home, '.config', 'fish', 'functions', 'upex.fish'),
+  ];
+  let docs = null;
+  if (platform === 'win32') {
+    // Ask Windows: Documents is often moved into OneDrive.
+    // UTF-8 so a non-ASCII Documents path survives the pipe.
+    const ps = '[Console]::OutputEncoding=[Text.Encoding]::UTF8; [Environment]::GetFolderPath("MyDocuments")';
+    const r = spawnSync('powershell.exe', ['-NoProfile', '-Command', ps], { encoding: 'utf-8', timeout: 5000 });
+    docs = r.stdout?.trim() || path.join(home, 'Documents');
+  }
+  for (const dir of docs ? ['PowerShell', 'WindowsPowerShell'] : ['powershell']) {
+    for (const name of ['Microsoft.PowerShell_profile.ps1', 'profile.ps1']) {
+      files.push(path.join(docs || path.join(home, '.config'), dir, name));
+    }
+  }
+  return files.filter(f => fs.existsSync(f));
+}
+
+function shellChecks() {
+  const out = [];
+  let cmdWrapper = false;
+
+  if (platform === 'win32') {
+    const shimDir = findShimDir();
+    const bat = shimDir && path.join(shimDir, 'upex.bat');
+    if (!shimDir) out.push(['warn', 'cmd wrapper', 'upex is not installed globally (npm link)']);
+    else if (!fs.existsSync(bat)) out.push(['warn', 'cmd wrapper', 'missing, run: upex setup cmd']);
+    else if (readText(bat) !== CMD_WRAPPER) out.push(['warn', 'cmd wrapper', 'outdated, run: upex setup cmd']);
+    else { out.push(['ok', 'cmd wrapper', bat]); cmdWrapper = true; }
+  }
+
+  const profiles = profileFiles().map(f => ({ f, text: readText(f) }));
+  const withWrapper = profiles.filter(p => p.text.includes('__resolve')).map(p => p.f);
+  const withCompletion = profiles.filter(p => p.text.includes('upex completion') || p.text.includes('__names')).map(p => p.f);
+  if (withWrapper.length) out.push(['ok', 'cd wrapper', withWrapper.join(', ')]);
+  else if (!cmdWrapper) out.push(['warn', 'cd wrapper', 'not in any shell profile, see: upex setup']);
+  // Completion is optional, so a missing one is only a hint.
+  out.push(withCompletion.length
+    ? ['ok', 'completion', withCompletion.join(', ')]
+    : ['skip', 'completion', 'not set up (optional), see: upex completion --help']);
+  return out;
+}
+
+// Rows of [status, check, detail]; status is ok | warn | fail | skip.
+export function runChecks() {
+  let links;
+  try {
+    links = loadLinks();
+    loadConfig();
+  } catch (err) {
+    return [['fail', 'store', err.message.split('\n')[0]]];
+  }
+  const rows = [['ok', 'store', `${plural(Object.keys(links).length, 'shortcut')} in ${LINKS_FILE}`]];
+
+  const broken = Object.keys(links).filter(n => links[n].path && !fs.existsSync(links[n].path));
+  rows.push(broken.length
+    ? ['warn', 'paths', `${plural(broken.length, 'broken shortcut')}: ${broken.join(', ')} (upex check)`]
+    : ['ok', 'paths', 'all paths exist']);
+
+  const badOpener = Object.keys(links).filter(n => links[n].opener && !openerKey(links[n].opener));
+  if (badOpener.length) rows.push(['warn', 'default openers', `unknown opener on: ${badOpener.join(', ')} (upex edit <name> --no-opener)`]);
+
+  const missing = [];
+  for (const [ws, entries] of Object.entries(loadWorkspaces())) {
+    for (const e of Array.isArray(entries) ? entries : []) {
+      // Subpaths ("web/src") count; fuzzy matches don't.
+      const ok = typeof e?.shortcut === 'string' && resolveTarget(e.shortcut, links)?.exact;
+      if (!ok) missing.push(`${ws}:${e?.shortcut ?? '?'}`);
+    }
+  }
+  if (missing.length) rows.push(['warn', 'workspaces', `missing shortcuts: ${missing.join(', ')}`]);
+
+  // One row per opener; aliases like code/vscode share a display name.
+  const seen = new Set(['Copy path']);
+  for (const [key, app] of Object.entries(getAppMap())) {
+    if (seen.has(app.displayName)) continue;
+    seen.add(app.displayName);
+    const r = checkOpener(key);
+    rows.push(r.ok ? ['ok', app.displayName, r.command] : ['warn', app.displayName, r.message.split('\n')[0]]);
+  }
+
+  return [...rows, ...shellChecks()];
+}
+
+export function registerDoctor(program) {
+  program
+    .command('doctor')
+    .description('Check the store, openers, shell wrapper and completion')
+    .action(() => {
+      ui.heading('upex doctor');
+      const rows = runChecks();
+      ui.table(rows.map(([status, check, detail]) => [ui.tag[status], chalk.bold(check), detail]));
+      ui.blank();
+      const warns = rows.filter(r => r[0] === 'warn').length;
+      const fails = rows.filter(r => r[0] === 'fail').length;
+      if (fails) ui.error(`${plural(fails, 'problem')} found.`);
+      else if (warns) ui.warn(`${plural(warns, 'warning')}, everything else is fine.`);
+      else ui.success('All good.');
+      ui.blank();
+      if (fails) process.exit(1);
+    });
+}

package/src/commands/edit.js

@@ -0,0 +1,85 @@
+/**
+ * edit.js -- Update the target of an existing shortcut.
+ * Usage: upex edit <name> [target] [--opener <app> | --no-opener]
+ *   folder shortcut: target is the new path (defaults to cwd)
+ *   URL / app shortcut: target is the new URL / command (required)
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { setLink, loadLinks, targetField } from '../store.js';
+import { resolveName } from '../fuzzy.js';
+import { openerKey } from '../launcher.js';
+import * as ui from '../ui.js';
+
+// Entry with the opener set (string) or cleared (false); null after printing why not.
+export function withOpener(entry, opener) {
+  const { opener: _old, ...rest } = entry;
+  if (opener === false) return rest;
+  if (!entry.path) {
+    ui.error('A default opener only applies to folder shortcuts.');
+    return null;
+  }
+  const key = openerKey(opener);
+  if (!key) {
+    ui.error(`Unknown opener "${opener}". Add custom ones with "upex app".`);
+    return null;
+  }
+  return { ...rest, opener: key };
+}
+
+export function registerEdit(program) {
+  program
+    .command('edit <name> [target]')
+    .description('Update a shortcut\'s path (or URL / app command) or its default opener')
+    .summary('Update a shortcut\'s path, URL, command or opener')
+    .option('-o, --opener <app>', 'Open this folder shortcut in <app> by default')
+    .option('--no-opener', 'Clear the default opener')
+    .action((name, target, options) => {
+      const links = loadLinks();
+      const resolved = resolveName(name, links);
+
+      if (!resolved) {
+        ui.error(`Shortcut not found: ${name}`);
+        return;
+      }
+
+      if (!resolved.exact) {
+        ui.warn(`No exact match. Did you mean "${resolved.name}"?`);
+        ui.info(`Run: upex edit ${resolved.name}${target ? ' ' + target : ''}`);
+        return;
+      }
+
+      const entry = links[name];
+      const field = targetField(entry);
+
+      // Only the opener changes: leave the target alone.
+      if (options.opener !== undefined && !target) {
+        const next = withOpener(entry, options.opener);
+        if (!next) process.exit(1);
+        setLink(name, next);
+        ui.success(next.opener ? `${name} now opens in ${next.opener}` : `${name}: default opener cleared`);
+        return;
+      }
+
+      let value = target;
+
+      if (field === 'path') {
+        value = target ? path.resolve(target) : process.cwd();
+        if (!fs.existsSync(value)) {
+          ui.error(`Path does not exist: ${value}`);
+          process.exit(1);
+        }
+      } else if (!value) {
+        ui.error(`Provide the new ${field === 'url' ? 'URL' : 'app path or command'}: upex edit ${name} <${field}>`);
+        process.exit(1);
+      }
+
+      const next = options.opener === undefined ? entry : withOpener(entry, options.opener);
+      if (!next) process.exit(1);
+      setLink(name, { ...next, [field]: value });
+      ui.success(`Updated: ${name}`);
+      ui.dim(`Old: ${entry[field] || '(none)'}`);
+      ui.dim(`New: ${value}`);
+    });
+}

package/src/commands/help.js

@@ -0,0 +1,45 @@
+/**
+ * help.js -- Show structured command reference, built from the registered commands.
+ */
+
+import chalk from 'chalk';
+import * as ui from '../ui.js';
+
+// "<name> [target...] [--tag <tags>]" from a command's arguments and options.
+function argsOf(cmd) {
+  const args = cmd.registeredArguments.map((a) => {
+    const n = a.name() + (a.variadic ? '...' : '');
+    return a.required ? `<${n}>` : `[${n}]`;
+  });
+  const opts = cmd.options.map(o => `[${o.flags.replace(/^-\w, /, '')}]`);
+  return [...args, ...opts].join(' ');
+}
+
+export function registerHelp(program) {
+  program
+    .command('help')
+    .description('Show all available commands')
+    .action(() => {
+      ui.heading('upex -- command reference');
+
+      // The default action (no sub-command) has no Command object, so it is listed by hand.
+      const help = program.createHelp();
+      const rows = [
+        ['upex', '[--app <app>]', 'Open the interactive selector and choose shortcut/app'],
+        ...help.visibleCommands(program).map(c => [
+          [c.name(), ...c.aliases()].join('|'),
+          argsOf(c),
+          help.subcommandDescription(c),
+        ]),
+        ['<name>', '[app] [count]', 'Open shortcut (app: vscode, cmd, claude, ...)'],
+      ];
+
+      ui.table([
+        [chalk.bold('COMMAND'), chalk.bold('ARGS'), chalk.bold('DESCRIPTION')],
+        ...rows.map(([cmd, args, desc]) => [chalk.bold(cmd), args || chalk.dim('--'), desc]),
+      ], { header: true });
+      ui.blank();
+      ui.dim('Run "upex <command> --help" for details.');
+      ui.blank();
+    });
+}

package/src/commands/last.js

@@ -0,0 +1,23 @@
+/**
+ * last.js -- Reopen the most recently used shortcut.
+ * Usage: upex last   (or the shorthand: upex -)
+ */
+
+import { lastUsedName } from '../store.js';
+import { handleOpen } from './open.js';
+import * as ui from '../ui.js';
+
+export function registerLast(program) {
+  program
+    .command('last')
+    .description('Reopen the most recently used shortcut')
+    .summary('Reopen the most recent shortcut (alias: upex -)')
+    .action(() => {
+      const name = lastUsedName();
+      if (!name) {
+        ui.warn('No shortcut has been used yet.');
+        process.exit(1);
+      }
+      return handleOpen(name);
+    });
+}

package/src/commands/list.js

@@ -0,0 +1,76 @@
+/**
+ * list.js -- Show all saved shortcuts.
+ * Usage: upex list
+ */
+
+import fs from 'node:fs';
+import nodePath from 'node:path';
+import chalk from 'chalk';
+import { loadLinks } from '../store.js';
+import { gitStatus } from '../git.js';
+import * as ui from '../ui.js';
+
+// Compact git cell: "main" (clean) or "main*" (dirty).
+function gitCell(filepath) {
+  const git = filepath ? gitStatus(filepath) : null;
+  if (!git) return chalk.dim('--');
+  return git.dirty ? chalk.yellow(`${git.branch}*`) : chalk.magenta(git.branch);
+}
+
+export function registerList(program) {
+  program
+    .command('list [tag]')
+    .alias('ls')
+    .description('List all saved shortcuts (optionally filtered by tag)')
+    .option('-g, --git', 'Show each folder\'s current git branch')
+    .action((tag, options) => {
+      const showGit = !!options.git;
+      const links = loadLinks();
+      let entries = Object.entries(links);
+      if (tag) {
+        entries = entries.filter(([, e]) => Array.isArray(e.tags) && e.tags.includes(tag));
+      }
+
+      if (entries.length === 0) {
+        ui.blank();
+        ui.info(tag ? `No shortcuts tagged "${tag}".` : 'No shortcuts saved. Use: upex add <name> [path]');
+        ui.blank();
+        return;
+      }
+
+      ui.heading(tag ? `Shortcuts tagged #${tag}` : 'Saved Shortcuts');
+
+      const header = [chalk.bold('#'), chalk.bold('NAME'), chalk.bold('APP'), chalk.bold('PATH')];
+      if (showGit) header.push(chalk.bold('GIT'));
+      header.push(chalk.bold('TAGS'), chalk.bold('STATUS'));
+
+      const rows = [
+        header,
+        ...entries.map(([name, entry], i) => {
+          const filepath = entry.path;
+          const appLabel = entry.terminal ? chalk.cyan('cmd')
+            : entry.app
+            ? chalk.cyan(nodePath.basename(entry.app).replace(/\.[^.]+$/, ''))
+            : entry.url ? chalk.cyan('url') : chalk.dim(entry.opener || '--');
+          const exists = filepath ? fs.existsSync(filepath) : !!(entry.app || entry.url);
+          const pathDisplay = filepath
+            ? (exists ? filepath : chalk.dim(filepath))
+            : entry.url ? chalk.blue(entry.url) : entry.terminal ? entry.app : chalk.dim('(app only)');
+          const status = exists ? ui.tag.ok : ui.tag.fail;
+          const tags = Array.isArray(entry.tags) && entry.tags.length
+            ? chalk.dim(entry.tags.join(', '))
+            : chalk.dim('--');
+          const row = [chalk.dim(String(i + 1)), chalk.bold(name), appLabel, pathDisplay];
+          if (showGit) row.push(gitCell(filepath));
+          row.push(tags, status);
+          return row;
+        }),
+      ];
+
+      ui.table(rows, { header: true });
+      ui.blank();
+      ui.separator();
+      ui.dim(`${entries.length} shortcut${entries.length === 1 ? '' : 's'}${tag ? ` tagged #${tag}` : ' total'}`);
+      ui.blank();
+    });
+}

package/src/commands/open.js

@@ -0,0 +1,195 @@
+/**
+ * open.js -- Open a shortcut path or launch it in an app.
+ * Default command: upex <name> [app]
+ * Hidden command: upex __resolve <name>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { loadLinks, recordUse } from '../store.js';
+import { resolveTarget, didYouMean } from '../fuzzy.js';
+import { launchApp, launchExecutable, launchUrl } from '../launcher.js';
+import * as ui from '../ui.js';
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// Folder path of a shortcut plus an optional subpath ("web/src").
+const withSub = (entry, sub) => (entry.path && sub ? path.join(entry.path, sub) : entry.path);
+
+// Resolve a name to a usable folder path and record the use.
+// On failure prints nothing (or `loud` message) and exits 1.
+function resolveFolder(name, { loud = false } = {}) {
+  const links = loadLinks();
+  const resolved = resolveTarget(name, links);
+
+  if (!resolved) {
+    if (loud) ui.error(`Shortcut not found: ${name}`);
+    process.exit(1);
+  }
+
+  const entry = links[resolved.name];
+  const targetPath = withSub(entry, resolved.sub);
+
+  if (!targetPath || !fs.existsSync(targetPath)) {
+    if (loud) ui.error(targetPath ? `Path does not exist: ${targetPath}` : `No folder path for "${resolved.name}".`);
+    process.exit(1);
+  }
+
+  recordUse(resolved.name);
+  return targetPath;
+}
+
+// Raw path to stdout (no formatting) -- consumed by `cd $(upex go <name>)`.
+function resolveToStdout(name, opts) {
+  process.stdout.write(resolveFolder(name, opts));
+}
+
+export function registerResolve(program) {
+  program
+    .command('__resolve <name>', { hidden: true })
+    .description('(internal) Resolve a shortcut name to its path')
+    // Wrappers send a lone `upex --help` here; exit 1 so they fall through to real help.
+    .helpOption(false)
+    .action((name) => {
+      // Wrappers route every bare arg through here; never let fuzzy matching
+      // shadow a real subcommand (e.g. "list" hijacked into a cd).
+      const taken = program.commands.some(c => c.name() === name || c.aliases().includes(name));
+      if (taken) process.exit(1);
+      resolveToStdout(name);
+    });
+}
+
+/**
+ * Public path-printing command: `cd $(upex go <name>)`.
+ */
+export function registerGo(program) {
+  program
+    .command('go <name> [start...]')
+    .description('Print a shortcut\'s path (cd via shell wrapper); extra args run as a command there')
+    .summary('Print a path (cd via wrapper); extra args run there')
+    // Let flags in the start command (e.g. "claude --model x") pass through.
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .allowUnknownOption()
+    .action((name, start = []) => {
+      if (!start.length) return resolveToStdout(name, { loud: true });
+
+      const targetPath = resolveFolder(name, { loud: true });
+      const cwd = isFile(targetPath) ? path.dirname(targetPath) : targetPath;
+      const r = spawnSync(start.join(' '), { cwd, stdio: 'inherit', shell: true });
+      process.exit(r.status ?? 1);
+    });
+}
+
+/**
+ * Handle the default open/launch action.
+ * Returns true when opened; in batch mode a failure returns false instead of exiting.
+ */
+export async function handleOpen(name, app, count = 1, startCmd = '', { batch = false } = {}) {
+  // In batch mode (group/workspace open) a bad shortcut must not exit the whole run.
+  const bail = (fn) => { fn(); if (batch) return true; process.exit(1); };
+
+  const links = loadLinks();
+  const resolved = resolveTarget(name, links);
+
+  if (!resolved) {
+    if (bail(() => {
+      ui.error(`Shortcut not found: ${name}`);
+      const hint = didYouMean(name, Object.keys(links));
+      if (hint) ui.dim(hint);
+    })) return false;
+  }
+
+  const shortcutName = resolved.name;
+  const entry = links[shortcutName];
+
+  if (resolved.sub && !entry.path) {
+    if (bail(() => ui.error(`"${shortcutName}" has no folder, so "${resolved.sub}" can't be opened inside it.`))) return false;
+  }
+
+  // ── URL shortcut: open in the browser directly ──
+  if (entry.url) {
+    const result = launchUrl(entry.url);
+    if (!result.ok) {
+      if (bail(() => ui.error(result.message))) return false;
+    }
+    recordUse(shortcutName);
+    if (!resolved.exact) {
+      ui.dim(`matched "${name}" --> "${shortcutName}"`);
+    }
+    ui.heading(shortcutName);
+    console.log(`  ${chalk.dim('url')}    ${chalk.bold(result.url)}`);
+    ui.blank();
+    return true;
+  }
+
+  // ── App shortcut: launch stored executable directly ──
+  if (entry.app && !app && !resolved.sub) {
+    // A command line opens a terminal in the home folder and runs there.
+    const result = entry.terminal ? launchApp('cmd', os.homedir(), 1, entry.app) : launchExecutable(entry.app);
+
+    if (!result.ok) {
+      if (bail(() => ui.error(result.message))) return false;
+    }
+
+    recordUse(shortcutName);
+
+    if (!resolved.exact) {
+      ui.dim(`matched "${name}" --> "${shortcutName}"`);
+    }
+
+    ui.heading(shortcutName);
+    console.log(`  ${chalk.dim('app')}    ${chalk.bold(result.displayName)}`);
+    if (entry.terminal) console.log(`  ${chalk.dim('run')}    ${entry.app}`);
+    if (entry.path) {
+      console.log(`  ${chalk.dim('path')}   ${entry.path}`);
+    }
+    ui.blank();
+    return true;
+  }
+
+  // ── Folder shortcut: open in specified or default opener ──
+  const targetPath = withSub(entry, resolved.sub);
+
+  if (!targetPath) {
+    if (bail(() => {
+      ui.warn(`No folder path stored for "${shortcutName}".`);
+      ui.dim(`This is an app shortcut. Run without an opener: upex ${shortcutName}`);
+    })) return false;
+  }
+
+  if (!fs.existsSync(targetPath)) {
+    if (bail(() => {
+      ui.warn(`Path does not exist: ${targetPath}`);
+      ui.dim(`Use "upex edit ${shortcutName} <newPath>" to update.`);
+    })) return false;
+  }
+
+  // No opener given: the shortcut's own, else a file opens in its default app and a folder in Explorer.
+  const appKey = app || entry.opener || (isFile(targetPath) ? 'open' : 'explorer');
+  const result = launchApp(appKey, targetPath, count, startCmd);
+
+  if (!result.ok) {
+    if (bail(() => ui.error(result.message))) return false;
+  }
+
+  recordUse(shortcutName);
+
+  // -- Structured output card --
+  if (!resolved.exact) {
+    ui.dim(`matched "${name}" --> "${shortcutName}"`);
+  }
+
+  ui.heading(shortcutName);
+
+  const appLabel = result.displayName || appKey;
+  console.log(`  ${chalk.dim('app')}    ${chalk.bold(appLabel)}`);
+  console.log(`  ${chalk.dim('path')}   ${targetPath}`);
+  ui.blank();
+  return true;
+}