dex-termux-cli 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+![Dex Banner](./icon/banner.png)
+
+<p align="center">
+  <img src="./icon/icon-dex.png" alt="Dex icon" width="124" />
+</p>
+
+<h1 align="center">Dex Termux CLI</h1>
+
+<p align="center">
+  CLI visual para Termux con búsqueda guiada, árbol legible, explicación de comandos y flujos de instalación segura para proyectos dentro de Android storage.
+</p>
+
+<p align="center">
+  <img alt="platform" src="https://img.shields.io/badge/platform-Termux-111111?style=flat-square&labelColor=F97316&color=1F2937">
+  <img alt="storage" src="https://img.shields.io/badge/storage-Android-111111?style=flat-square&labelColor=0F766E&color=1F2937">
+  <img alt="safe-mode" src="https://img.shields.io/badge/safe%20mode-Python%20%7C%20Node%20%7C%20PHP-111111?style=flat-square&labelColor=2563EB&color=1F2937">
+  <img alt="status" src="https://img.shields.io/badge/status-active-111111?style=flat-square&labelColor=7C3AED&color=1F2937">
+</p>
+
+<p align="center">
+  <strong>Explorar.</strong> <strong>Entender.</strong> <strong>Instalar.</strong> <strong>Entrar al modo seguro.</strong>
+</p>
+
+> Estado actual: soporte seguro para Python, Node y PHP.
+
+## Visión general
+
+Dex está pensado para mejorar el trabajo diario en Termux cuando el proyecto vive dentro de almacenamiento Android. En lugar de obligar al usuario a resolver todo manualmente, Dex ofrece una capa más clara para explorar, entender y preparar proyectos sin perder control del entorno real.
+
+## En qué destaca
+
+- interfaz más legible para tareas comunes de terminal
+- detección del lenguaje del proyecto actual
+- instalación segura para proyectos en Android storage
+- shell segura por proyecto con el contexto correcto
+- enfoque práctico en lugar de automatización opaca
+
+## Capacidades principales
+
+| Comando | Uso principal |
+| --- | --- |
+| `dex -m` | abre el menú principal |
+| `dex -b` | busca archivos o carpetas |
+| `dex -e` | explica comandos comunes |
+| `dex -t` | muestra árbol guiado |
+| `dex -a` | acceso rápido a Android |
+| `dex -i` | instala dependencias del proyecto actual |
+| `dex -r` | abre el modo seguro del proyecto |
+
+## Qué resuelve
+
+- salida visual más clara que varios comandos crudos de terminal
+- exploración rápida de carpetas y archivos sin recordar tanta sintaxis
+- detección del lenguaje del proyecto actual
+- instalación segura cuando Android storage rompe el flujo normal
+- shell segura por proyecto para seguir trabajando con el entorno correcto
+
+## Instalación segura por lenguaje
+
+| Lenguaje | Estrategia de instalación | Modo seguro |
+| --- | --- | --- |
+| Python | `pip`, `requirements.txt`, `pyproject.toml`, `setup.py` o imports inferidos | `venv` seguro |
+| Node | `npm ci` o `npm install` | copia segura del proyecto en `HOME` |
+| PHP | `composer install --no-interaction` | copia segura del proyecto en `HOME` |
+
+## Cómo funciona el modo seguro
+
+### Python
+Dex prepara un `venv` seguro y abre una shell con el entorno correcto para ejecutar `python`, `pip` o el entrypoint del proyecto.
+
+### Node
+Dex puede trabajar con una copia segura del proyecto fuera de Android storage para que `npm` y `node_modules` no choquen con las limitaciones del almacenamiento compartido.
+
+### PHP
+Dex puede instalar dependencias con `composer` en una copia segura del proyecto y abrir una shell lista para seguir trabajando desde ahí.
+
+## Estado actual
+
+- instalación segura activa para Python, Node y PHP
+- shell segura activa para Python, Node y PHP
+- branding base ya integrado al repositorio
+- lectura del proyecto centrada en Termux y Android storage
+
+## Roadmap
+
+- soporte seguro para Ruby, Go y Rust
+- mejor traducción de errores nativos y de compilación
+- ejecución guiada de entrypoints del proyecto
+- refinamiento final de branding y presentación pública

package/bin/Dex

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/app/main.js';
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/dex

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/app/main.js';
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/data/commands/explain.json

@@ -0,0 +1,74 @@
+{
+  "ls": {
+    "summary": "Lista archivos y carpetas.",
+    "usage": "ls\nls -lah\nls /sdcard/Download",
+    "risk": "bajo",
+    "notes": [
+      "Usa -l para ver detalles y -a para mostrar ocultos.",
+      "En Termux, ls -lah es una combinacion util para inspeccionar carpetas."
+    ]
+  },
+  "cd": {
+    "summary": "Cambia de carpeta actual.",
+    "usage": "cd carpeta\ncd ..\ncd ~\ncd /sdcard",
+    "risk": "bajo",
+    "notes": [
+      "cd .. sube un nivel.",
+      "cd ~ vuelve a tu home de Termux."
+    ]
+  },
+  "rm": {
+    "summary": "Borra archivos o carpetas.",
+    "usage": "rm archivo.txt\nrm -r carpeta",
+    "risk": "alto",
+    "notes": [
+      "No manda a papelera. Borra directamente.",
+      "Ten cuidado con rm -r y especialmente con rutas fuera de tu carpeta actual."
+    ]
+  },
+  "cp": {
+    "summary": "Copia archivos o carpetas.",
+    "usage": "cp origen destino\ncp -r carpeta_a carpeta_b",
+    "risk": "medio",
+    "notes": [
+      "Usa -r para copiar carpetas completas.",
+      "Puede sobrescribir si el destino ya existe."
+    ]
+  },
+  "mv": {
+    "summary": "Mueve o renombra archivos y carpetas.",
+    "usage": "mv origen destino\nmv nombre_viejo nombre_nuevo",
+    "risk": "medio",
+    "notes": [
+      "Sirve tanto para mover como para renombrar.",
+      "Si el destino existe, puedes sobrescribir sin querer."
+    ]
+  },
+  "pkg": {
+    "summary": "Instala y gestiona paquetes en Termux.",
+    "usage": "pkg search git\npkg install git\npkg update && pkg upgrade",
+    "risk": "medio",
+    "notes": [
+      "Es la forma comoda de usar apt dentro de Termux.",
+      "Antes de instalar mucho, conviene actualizar repos y paquetes."
+    ]
+  },
+  "git": {
+    "summary": "Control de versiones y clonacion de repositorios.",
+    "usage": "git clone URL\ngit status\ngit add .\ngit commit -m \"mensaje\"",
+    "risk": "medio",
+    "notes": [
+      "git status es el comando base para saber en que estado estas.",
+      "No uses comandos destructivos si no sabes exactamente que hacen."
+    ]
+  },
+  "find": {
+    "summary": "Busca archivos y carpetas desde terminal.",
+    "usage": "find . -name \"*.js\"\nfind /sdcard -iname \"foto*\"",
+    "risk": "bajo",
+    "notes": [
+      "Puede ser lento en rutas muy grandes.",
+      "Dex -b esta pensado precisamente para evitarte recordar esta sintaxis."
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "dex-termux-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Termux CLI for Android with guided search, readable tree views, command help, and safe project install flows for Python, Node, and PHP.",
+  "keywords": [
+    "termux",
+    "android",
+    "cli",
+    "python",
+    "node",
+    "php",
+    "safe-shell"
+  ],
+  "license": "MIT",
+  "bin": "./bin/dex",
+  "scripts": {
+    "start": "node ./bin/dex",
+    "help": "node ./bin/dex --help"
+  },
+  "author": "farllirs",
+  "files": [
+    "bin/dex",
+    "src",
+    "data/commands/explain.json",
+    "README.md",
+    "icon"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farllirs/dex-termux-cli.git"
+  },
+  "homepage": "https://github.com/farllirs/dex-termux-cli#readme",
+  "bugs": {
+    "url": "https://github.com/farllirs/dex-termux-cli/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/app/main.js

@@ -0,0 +1,65 @@
+import { parseArgs } from '../core/args.js';
+import { loadUserConfig } from '../core/config.js';
+import { runAndroidShellCommand } from '../commands/android-shell.js';
+import { runExplainCommand } from '../commands/explain.js';
+import { runInstallCommand } from '../commands/install.js';
+import { runMenuCommand } from '../commands/menu.js';
+import { runSafeShellCommand } from '../commands/safe-shell.js';
+import { runSearchCommand } from '../commands/search.js';
+import { runTreeCommand } from '../commands/tree.js';
+import { printHelp, printProjectContextLine } from '../ui/output.js';
+import { detectProjectContext, formatProjectContext } from '../utils/project-context.js';
+
+export async function main(argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv);
+  const config = await loadUserConfig();
+
+  if (config.features.projectBadge) {
+    const context = await detectProjectContext();
+    if (context) {
+      printProjectContextLine(formatProjectContext(context));
+    }
+  }
+
+  if (parsed.help || !argv.length) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.command === 'search') {
+    await runSearchCommand(parsed);
+    return;
+  }
+
+  if (parsed.command === 'explain') {
+    await runExplainCommand(parsed);
+    return;
+  }
+
+  if (parsed.command === 'menu') {
+    await runMenuCommand();
+    return;
+  }
+
+  if (parsed.command === 'tree') {
+    await runTreeCommand(parsed);
+    return;
+  }
+
+  if (parsed.command === 'android') {
+    await runAndroidShellCommand();
+    return;
+  }
+
+  if (parsed.command === 'install') {
+    await runInstallCommand();
+    return;
+  }
+
+  if (parsed.command === 'safe-shell') {
+    await runSafeShellCommand();
+    return;
+  }
+
+  printHelp();
+}

package/src/commands/android-shell.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { getUserConfigPath, loadUserConfig } from '../core/config.js';
+
+const ANDROID_ROOT = '/sdcard';
+
+export async function runAndroidShellCommand() {
+  const config = await loadUserConfig();
+
+  if (!config.features.androidShortcut) {
+    throw new Error(
+      `La opcion Android esta desactivada. Activa features.androidShortcut en ${getUserConfigPath()}`,
+    );
+  }
+
+  try {
+    await fs.access(ANDROID_ROOT);
+  } catch {
+    throw new Error(`No se puede acceder a la ruta Android: ${ANDROID_ROOT}`);
+  }
+
+  const shell = process.env.SHELL || '/data/data/com.termux/files/usr/bin/sh';
+
+  console.log(`Abriendo shell en ${ANDROID_ROOT}`);
+  console.log('Escribe exit para volver.');
+  console.log('');
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(shell, {
+      cwd: ANDROID_ROOT,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        DEX_CONTEXT: 'android-shell',
+      },
+    });
+
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        reject(new Error(`La shell Android termino por senal: ${signal}`));
+        return;
+      }
+
+      if (code && code !== 0) {
+        reject(new Error(`La shell Android termino con codigo ${code}`));
+        return;
+      }
+
+      resolve();
+    });
+  });
+}

package/src/commands/explain.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { printExplainEntry, printSection } from '../ui/output.js';
+import { chooseExplainTopic } from '../ui/prompt.js';
+
+const EXPLAIN_DATA_PATH = path.resolve(process.cwd(), 'data/commands/explain.json');
+
+export async function runExplainCommand({ topic }) {
+  const entries = await loadExplainEntries();
+  const selectedTopic = topic ? topic.toLowerCase() : await chooseExplainTopic(entries);
+  const entry = entries[selectedTopic];
+
+  if (!entry) {
+    const available = Object.keys(entries).join(', ');
+    throw new Error(`No conozco ese comando todavia. Disponibles: ${available}`);
+  }
+
+  printSection(`Explicar: ${selectedTopic}`);
+  console.log(printExplainEntry(selectedTopic, entry));
+}
+
+async function loadExplainEntries() {
+  const raw = await fs.readFile(EXPLAIN_DATA_PATH, 'utf8');
+  return JSON.parse(raw);
+}