@orxataguy/tyr 1.0.5 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orxataguy/tyr",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "type": "module",
   "bin": {
     "tyr": "./bin/tyr.js"

package/src/core/Container.ts

@@ -6,6 +6,8 @@ import { GitManager } from '../lib/GitManager.js';
 import { SystemManager } from '../lib/SystemManager.js';
 import { SQLManager } from '../lib/SQLManager.js';
 import { WebManager } from '../lib/WebManager.js';
+import { WorkspaceManager } from '../lib/WorkspaceManager.js';
+import { JiraManager } from '../lib/JiraManager.js';
 import { Logger, createLogger } from './Logger.js';
 
 export type { Logger };
@@ -20,6 +22,8 @@ export interface ServiceContainer {
     sys: SystemManager;
     db: SQLManager;
     web: WebManager;
+    workspace: WorkspaceManager;
+    jira: JiraManager;
 }
 
 export class Container {
@@ -33,17 +37,21 @@ export class Container {
         const logger = createLogger(isDebug);
         const shell = new ShellManager();
         const db = new SQLManager();
+        const web = new WebManager(logger);
+        const fs = new FileSystemManager(logger);
 
         this.services = {
             logger,
             shell,
             db,
-            web: new WebManager(logger),
-            fs: new FileSystemManager(logger),
+            web,
+            fs,
             pkg: new PackageManager(shell, logger),
             docker: new DockerManager(shell, logger),
             git: new GitManager(shell, logger),
             sys: new SystemManager(shell, logger),
+            workspace: new WorkspaceManager(shell, fs, logger),
+            jira: new JiraManager(web, shell, logger),
         };
     }
 

package/src/core/Kernel.ts

@@ -11,6 +11,7 @@ import rem from './sys/rem';
 import doc from './sys/doc';
 import ai from './sys/ai';
 import config from './sys/config';
+import help from './sys/help';
 
 import { TyrError } from './TyrError';
 
@@ -126,6 +127,20 @@ export class Kernel {
             return;
         }
 
+        // --help / -h: lista todos los comandos disponibles con su documentación
+        if (commandName === '--help' || commandName === '-h') {
+            const helpContext = {
+                ...this.container.get(),
+                frameworkRoot: this.frameworkRoot,
+                userRoot: this.userRoot,
+                run: async () => {},
+                task: async <T>(_: string, action: () => Promise<T> | T) => action(),
+                fail: (msg: string) => { throw new Error(msg); },
+            } as any;
+            await help(helpContext)(args.slice(1));
+            return;
+        }
+
         const runInternal = async (cmd: string, cmdArgs: string[] = []) => {
             await this.handle([cmd, ...cmdArgs]);
         };

package/src/core/sys/config.ts

@@ -59,6 +59,33 @@ function detectShellRcFile(homeDir: string): string | null {
     return fallbacks.find(p => existsSync(p)) ?? path.join(homeDir, '.bashrc');
 }
 
+const PACKAGE_JSON_TEMPLATE = `{
+  "name": "tyr-commands",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "description": "Comandos personalizados de Tyr (~/.tyr/)",
+  "dependencies": {
+    "@orxataguy/tyr": "latest"
+  }
+}
+`;
+
+const TSCONFIG_TEMPLATE = `{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["commands/**/*.ts"]
+}
+`;
+
 const ENV_TEMPLATE = `# ~/.tyr/.env
 # Variables de entorno para Tyr. Este archivo nunca debe subirse a git.
 #
@@ -220,6 +247,27 @@ export default function config({ logger, fs: tyrFs, frameworkRoot, shell }: TyrC
                 logger.success(`Archivo creado: ${envPath}`);
             }
 
+            const packageJsonPath = path.join(userRoot, 'package.json');
+            if (!tyrFs.exists(packageJsonPath)) {
+                await tyrFs.write(packageJsonPath, PACKAGE_JSON_TEMPLATE);
+                logger.success(`Archivo creado: ${packageJsonPath}`);
+            }
+
+            const tsconfigPath = path.join(userRoot, 'tsconfig.json');
+            if (!tyrFs.exists(tsconfigPath)) {
+                await tyrFs.write(tsconfigPath, TSCONFIG_TEMPLATE);
+                logger.success(`Archivo creado: ${tsconfigPath}`);
+            }
+
+            logger.info('\nInstalando dependencias de tipos en ~/.tyr...');
+            shell.cd(userRoot);
+            try {
+                await shell.exec('npm install');
+                logger.success('Dependencias instaladas correctamente.');
+            } catch {
+                logger.warn('No se pudo ejecutar npm install en ~/.tyr. Hazlo manualmente.');
+            }
+
             if (repoUrl) {
                 logger.info('\nSubiendo configuración inicial al repositorio...');
                 shell.cd(userRoot);
@@ -234,6 +282,35 @@ export default function config({ logger, fs: tyrFs, frameworkRoot, shell }: TyrC
             }
         }
 
+        // Garantizar package.json + tsconfig.json + npm install siempre,
+        // tanto en init fresh como al clonar un repo existente.
+        const packageJsonPath = path.join(userRoot, 'package.json');
+        const tsconfigPath    = path.join(userRoot, 'tsconfig.json');
+        let needsInstall = false;
+
+        if (!tyrFs.exists(packageJsonPath)) {
+            await tyrFs.write(packageJsonPath, PACKAGE_JSON_TEMPLATE);
+            logger.success(`Archivo creado: ${packageJsonPath}`);
+            needsInstall = true;
+        }
+
+        if (!tyrFs.exists(tsconfigPath)) {
+            await tyrFs.write(tsconfigPath, TSCONFIG_TEMPLATE);
+            logger.success(`Archivo creado: ${tsconfigPath}`);
+            needsInstall = true;
+        }
+
+        if (needsInstall) {
+            logger.info('\nInstalando dependencias de tipos en ~/.tyr...');
+            shell.cd(userRoot);
+            try {
+                await shell.exec('npm install');
+                logger.success('Dependencias instaladas.');
+            } catch {
+                logger.warn('No se pudo ejecutar npm install en ~/.tyr. Hazlo manualmente.');
+            }
+        }
+
         const aliasesPath = path.join(userRoot, `aliases${ext}`);
         const pluginsPath = path.join(userRoot, `plugins${ext}`);
 

package/src/core/sys/help.ts

@@ -0,0 +1,149 @@
+import fs from 'fs';
+import path from 'path';
+import { TyrContext } from '../Kernel';
+
+interface CommandDoc {
+    name: string;
+    description: string;
+    usage: string;
+}
+
+/**
+ * Extrae el primer bloque JSDoc de un archivo .tyr.ts y lo parsea
+ * en descripción y ejemplos de uso.
+ */
+function parseCommandDoc(filePath: string): CommandDoc {
+    const fileName = path.basename(filePath, '.tyr.ts');
+    const content = fs.readFileSync(filePath, 'utf-8');
+
+    const match = content.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!match) {
+        return { name: fileName, description: '', usage: '' };
+    }
+
+    // Limpiar cada línea: eliminar el * inicial y espacios
+    const lines = match[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, '').trimEnd());
+
+    // Separar en descripción y bloque "Uso:"
+    const usoIndex = lines.findIndex(l => /^uso:/i.test(l.trim()));
+
+    let description = '';
+    let usage = '';
+
+    if (usoIndex !== -1) {
+        description = lines
+            .slice(0, usoIndex)
+            .filter(l => l.trim() !== '')
+            .join('\n')
+            .trim();
+
+        usage = lines
+            .slice(usoIndex + 1)
+            .filter(l => l.trim() !== '')
+            .map(l => l.trim())
+            .join('\n')
+            .trim();
+    } else {
+        description = lines.filter(l => l.trim() !== '').join('\n').trim();
+    }
+
+    return { name: fileName, description, usage };
+}
+
+export default function help({ userRoot }: TyrContext) {
+    return async (_args: string[]) => {
+        const commandsDir = path.join(userRoot, 'commands');
+
+        // ── ANSI ──────────────────────────────────────────────────────────
+        const reset  = '\x1b[0m';
+        const bold   = '\x1b[1m';
+        const dim    = '\x1b[2m';
+        const cyan   = '\x1b[36m';
+        const green  = '\x1b[32m';
+        const yellow = '\x1b[33m';
+        const gray   = '\x1b[90m';
+        const white  = '\x1b[37m';
+        // ──────────────────────────────────────────────────────────────────
+
+        const separator = `${gray}  ${'─'.repeat(50)}${reset}`;
+
+        console.log('');
+        console.log(`  ${bold}${cyan}tyr${reset}  ${white}Comandos disponibles${reset}`);
+        console.log(separator);
+        console.log('');
+
+        // Flags y comandos built-in del framework
+        const builtins = [
+            { name: '--help',    description: 'Muestra este listado de comandos.',          usage: 'tyr --help' },
+            { name: '--version', description: 'Muestra la versión instalada de tyr.',       usage: 'tyr --version' },
+            { name: '--config',  description: 'Configura tyr por primera vez.',             usage: 'tyr --config' },
+            { name: '--update',  description: 'Actualiza ~/.tyr desde el repositorio git.', usage: 'tyr --update' },
+            { name: '--upgrade', description: 'Actualiza el paquete npm de tyr.',           usage: 'tyr --upgrade' },
+            { name: 'gen',       description: 'Genera un nuevo comando a partir de una descripción con IA.', usage: 'tyr gen <nombre> "<descripción>"' },
+            { name: 'doc',       description: 'Levanta la documentación del framework en el navegador.', usage: 'tyr doc' },
+        ];
+
+        console.log(`  ${bold}${yellow}Framework${reset}`);
+        console.log('');
+
+        for (const cmd of builtins) {
+            console.log(`  ${bold}${green}${cmd.name.padEnd(14)}${reset}${dim}${cmd.description}${reset}`);
+            console.log(`  ${' '.repeat(14)}${gray}${cmd.usage}${reset}`);
+            console.log('');
+        }
+
+        // Comandos de usuario en ~/.tyr/commands/
+        if (!fs.existsSync(commandsDir)) {
+            console.log(separator);
+            console.log(`  ${yellow}No se encontró la carpeta de comandos: ${commandsDir}${reset}`);
+            console.log('');
+            return;
+        }
+
+        const files = fs.readdirSync(commandsDir)
+            .filter(f => f.endsWith('.tyr.ts'))
+            .sort();
+
+        if (files.length === 0) {
+            console.log(separator);
+            console.log(`  ${dim}No hay comandos en ${commandsDir}${reset}`);
+            console.log('');
+            return;
+        }
+
+        console.log(separator);
+        console.log('');
+        console.log(`  ${bold}${yellow}Comandos de usuario${reset}  ${gray}(~/.tyr/commands/)${reset}`);
+        console.log('');
+
+        for (const file of files) {
+            const doc = parseCommandDoc(path.join(commandsDir, file));
+
+            console.log(`  ${bold}${green}${doc.name}${reset}`);
+
+            if (doc.description) {
+                for (const line of doc.description.split('\n')) {
+                    console.log(`  ${dim}${line}${reset}`);
+                }
+            } else {
+                console.log(`  ${gray}Sin descripción${reset}`);
+            }
+
+            if (doc.usage) {
+                console.log('');
+                console.log(`  ${gray}  Uso:${reset}`);
+                for (const line of doc.usage.split('\n')) {
+                    console.log(`  ${cyan}    ${line}${reset}`);
+                }
+            }
+
+            console.log('');
+        }
+
+        console.log(separator);
+        console.log(`  ${dim}Genera un comando nuevo con ${cyan}tyr gen <nombre> "<qué debe hacer>"${reset}`);
+        console.log('');
+    };
+}

package/src/lib/FileSystemManager.ts

@@ -19,9 +19,28 @@ export class FileSystemManager {
     }
 
     private resolvePath(filePath: string): string {
-        return filePath.startsWith('~/')
-            ? path.join(homedir(), filePath.slice(2))
-            : filePath;
+        return this.expandPath(filePath);
+    }
+
+    /**
+     * @method expandPath
+     * @description Expands `~` and `$HOME` in a path string to the actual home directory.
+     * Useful for reading paths from environment variables (dotenv does not expand shell variables).
+     * @param {string} filePath - The path to expand.
+     * @returns {string} The expanded absolute path.
+     * @example
+     * const dir = fs.expandPath(process.env.INTEGRATIONS_DIR!);
+     * // "~/dev/datosBroker" → "/Users/mandreu/dev/datosBroker"
+     */
+    public expandPath(filePath: string): string {
+        const home = homedir();
+        if (filePath.startsWith('~/') || filePath === '~') {
+            return path.join(home, filePath.slice(1));
+        }
+        if (filePath.startsWith('$HOME/') || filePath === '$HOME') {
+            return path.join(home, filePath.slice(5));
+        }
+        return filePath;
     }
 
     /**

package/src/lib/GitManager.ts

@@ -64,6 +64,65 @@ export class GitManager {
             throw new TyrError(`Could not find the repository ` + repoUrl, e, 'Check if the repository exists or if you have the right permissions to clone it.');
         }
     }
+
+    /**
+     * @method cloneTo
+     * @description Clones a remote repository into a specific target directory.
+     * @param {string} repoUrl - The HTTPS or SSH URL of the repository.
+     * @param {string} destDir - The absolute path of the destination directory.
+     * @example
+     * await git.cloneTo('git@github.com:org/repo.git', '/path/to/dest');
+     */
+    public async cloneTo(repoUrl: string, destDir: string): Promise<void> {
+        this.logger.info(`Clonando ${repoUrl}...`);
+        const loader = this.shell.showLoader('Clonando repositorio...');
+        try {
+            await this.shell.exec(`git clone "${repoUrl}" "${destDir}"`);
+            await this.shell.exec(`git -C "${destDir}" config --add core.filemode false`);
+            loader.stop();
+            this.logger.success('Clonación completada.');
+        } catch (e) {
+            loader.stop();
+            throw new TyrError(`No se pudo clonar el repositorio: ${repoUrl}`, e, 'Comprueba que el repositorio existe y que tienes permisos para clonarlo.');
+        }
+    }
+
+    /**
+     * @method checkRepoExists
+     * @description Checks if a remote Git repository is accessible via ls-remote.
+     * @param {string} repoUrl - The URL of the repository to check.
+     * @returns {Promise<boolean>} True if the repository is reachable.
+     * @example
+     * const exists = await git.checkRepoExists('git@github.com:org/repo.git');
+     */
+    public async checkRepoExists(repoUrl: string): Promise<boolean> {
+        try {
+            await this.shell.exec(`git ls-remote "${repoUrl}" HEAD`);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * @method initWithRemote
+     * @description Removes an existing .git folder if present, then initialises a new Git repository
+     * in the given directory and configures a remote origin.
+     * @param {string} dir - The absolute path of the directory to initialise.
+     * @param {string} remoteUrl - The remote URL to set as origin.
+     * @example
+     * await git.initWithRemote('/path/to/dir', 'git@github.com:org/repo.git');
+     */
+    public async initWithRemote(dir: string, remoteUrl: string): Promise<void> {
+        try {
+            await this.shell.exec(
+                `cd "${dir}" && rm -rf .git && git init -b master && git remote add origin "${remoteUrl}" && git config --add core.filemode false && echo 'node_modules' >> .gitignore`
+            );
+            this.logger.success(`Repositorio Git inicializado en ${dir}`);
+        } catch (e) {
+            throw new TyrError(`No se pudo inicializar el repositorio en ${dir}`, e);
+        }
+    }
 }
 
 /**

package/src/lib/JiraManager.ts

@@ -0,0 +1,103 @@
+import { WebManager } from './WebManager.js';
+import { ShellManager } from './ShellManager.js';
+import { Logger } from '../core/Logger.js';
+
+interface JiraIssue {
+    key: string;
+    summary: string;
+    status: string;
+}
+
+/**
+ * @class JiraManager
+ * @description Integration with the Jira REST API. Allows fetching and selecting issues
+ * assigned to the current user. Falls back to manual branch input if Jira is unavailable.
+ *
+ * Required environment variables:
+ *   JIRA_URL   – e.g. https://yourcompany.atlassian.net
+ *   JIRA_TOKEN – base64 of "email:api_token" (Basic Auth)
+ */
+export class JiraManager {
+    private web: WebManager;
+    private shell: ShellManager;
+    private logger: Logger;
+
+    constructor(web: WebManager, shell: ShellManager, logger: Logger) {
+        this.web = web;
+        this.shell = shell;
+        this.logger = logger;
+    }
+
+    private get jiraUrl(): string | undefined {
+        return process.env.JIRA_URL;
+    }
+
+    private get jiraToken(): string | undefined {
+        return process.env.JIRA_TOKEN;
+    }
+
+    private async fetchMyIssues(): Promise<JiraIssue[]> {
+        if (!this.jiraUrl || !this.jiraToken) return [];
+
+        const jql = 'assignee = currentUser() AND status IN ("To develop","TO BE DONE",Backlog,"Pending Info",Developing,DEVELOPMENT,"In development",TEST,DESIGN,"To Do","In Progress")';
+        const url = `${this.jiraUrl}/rest/api/3/search?jql=${encodeURIComponent(jql)}`;
+
+        const data = await this.web.get(url, {
+            headers: { Authorization: `Basic ${this.jiraToken}` },
+        });
+
+        return (data.issues ?? []).map((issue: any) => ({
+            key: issue.key,
+            summary: issue.fields.summary,
+            status: issue.fields.status.name,
+        }));
+    }
+
+    /**
+     * @method selectIssue
+     * @description Presents the user's open Jira issues as an interactive list and returns
+     * the selected issue key (e.g. "PROJ-123"). If Jira is not configured or unreachable,
+     * falls back to a free-text prompt for a branch name.
+     * Returns null if the user chooses to skip.
+     * @returns {Promise<string | null>} The selected Jira key, a branch name, or null.
+     * @example
+     * const branch = await jira.selectIssue();
+     * if (branch) await workspace.tagWorkspace(dir, branch);
+     */
+    public async selectIssue(): Promise<string | null> {
+        // Try Jira API
+        if (this.jiraUrl && this.jiraToken) {
+            try {
+                const issues = await this.fetchMyIssues();
+                const choices = [
+                    ...issues.map(i => ({
+                        name: `${i.key} - ${i.summary} [${i.status}]`,
+                        value: i.key,
+                    })),
+                    { name: 'Sin ticket (introducir rama manualmente)', value: '__manual__' },
+                    { name: 'Omitir (no crear rama)', value: '__skip__' },
+                ];
+
+                const selected = await this.shell.select(choices, 'Selecciona un ticket de Jira:');
+
+                if (selected === '__skip__') return null;
+                if (selected === '__manual__') return this.askForBranch();
+
+                return selected;
+            } catch {
+                this.logger.warn('No se ha podido conectar con Jira. Introducción manual de rama.');
+            }
+        }
+
+        return this.askForBranch();
+    }
+
+    private async askForBranch(): Promise<string | null> {
+        const raw = await this.shell.input('Introduce el nombre de la nueva rama (vacío para omitir):');
+        if (!raw.trim()) return null;
+        // Normalise: take the last segment separated by '/'
+        return raw.trim().split('/').pop()?.toUpperCase() ?? raw.trim();
+    }
+}
+
+export const JiraManagerTests = {};

package/src/lib/ShellManager.ts

@@ -104,6 +104,86 @@ export class ShellManager {
 
         this.cwd = resolve(this.cwd, expandedPath);
     }
+
+    /**
+     * @method getCwd
+     * @description Returns the current working directory used by this instance.
+     * @returns {string} The current working directory.
+     * @example
+     * const dir = shell.getCwd();
+     */
+    public getCwd(): string {
+        return this.cwd;
+    }
+
+    /**
+     * @method confirm
+     * @description Prompts the user with a yes/no question via CLI.
+     * @param {string} question - The question to display.
+     * @param {boolean} defaultValue - Default answer if user presses Enter (default: false).
+     * @returns {Promise<boolean>} True if the user confirmed.
+     * @example
+     * const ok = await shell.confirm('¿Continuar?', false);
+     */
+    public async confirm(question: string, defaultValue: boolean = false): Promise<boolean> {
+        try {
+            const result = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'value',
+                message: question,
+                default: defaultValue,
+            }]);
+            return result.value;
+        } catch (e) {
+            throw new TyrError(`Error al mostrar la confirmación: ${question}`, e);
+        }
+    }
+
+    /**
+     * @method select
+     * @description Prompts the user to select one option from a list.
+     * @param {Array<{name: string, value: string}>} choices - The available options.
+     * @param {string} question - The question to display.
+     * @returns {Promise<string>} The selected value.
+     * @example
+     * const branch = await shell.select([{ name: 'main', value: 'main' }], '¿Qué rama?');
+     */
+    public async select(choices: { name: string; value: string }[], question: string): Promise<string> {
+        try {
+            const result = await inquirer.prompt([{
+                type: 'list',
+                name: 'value',
+                message: question,
+                choices,
+            }]);
+            return result.value;
+        } catch (e) {
+            throw new TyrError(`Error al mostrar la selección: ${question}`, e);
+        }
+    }
+
+    /**
+     * @method checkbox
+     * @description Prompts the user to select multiple options from a list.
+     * @param {Array<{name: string, value: string}>} choices - The available options.
+     * @param {string} question - The question to display.
+     * @returns {Promise<string[]>} The selected values.
+     * @example
+     * const widgets = await shell.checkbox(choices, '¿Qué widgets incluir?');
+     */
+    public async checkbox(choices: { name: string; value: string }[], question: string): Promise<string[]> {
+        try {
+            const result = await inquirer.prompt([{
+                type: 'checkbox',
+                name: 'value',
+                message: question,
+                choices,
+            }]);
+            return result.value;
+        } catch (e) {
+            throw new TyrError(`Error al mostrar las opciones: ${question}`, e);
+        }
+    }
 }
 
 /**
@@ -114,5 +194,8 @@ export const ShellManagerTests = {
     exec: { command: 'node -v' },
     cd: { path: '/tmp' },
     input: { question: 'Enter a test value:' },
-    showLoader: { message: 'Loading test...' }
+    showLoader: { message: 'Loading test...' },
+    confirm: { question: '¿Continuar?', defaultValue: false },
+    select: { choices: [{ name: 'Opción A', value: 'a' }, { name: 'Opción B', value: 'b' }], question: '¿Cuál eliges?' },
+    checkbox: { choices: [{ name: 'Item 1', value: '1' }, { name: 'Item 2', value: '2' }], question: '¿Cuáles quieres?' },
 };

package/src/lib/WebManager.ts

@@ -24,6 +24,46 @@ export class WebManager {
         }
     }
 
+    /**
+     * @method get
+     * @description Makes an HTTP GET request and returns the raw response data. Useful for REST APIs.
+     * @param {string} url - The URL to request.
+     * @param {AxiosRequestConfig} config - Optional Axios config (headers, params, etc.).
+     * @returns {Promise<any>} The response data.
+     * @example
+     * const data = await web.get('https://api.example.com/items', { headers: { Authorization: 'Bearer token' } });
+     */
+    public async get(url: string, config?: AxiosRequestConfig): Promise<any> {
+        try {
+            const response = await axios.get(url, config);
+            return response.data;
+        } catch (e: any) {
+            const status = e?.response?.status;
+            const err = new TyrError(`HTTP GET failed (${status ?? 'unknown'}): ${url}`, e, 'Check your network connection and the URL.');
+            (err as any).status = status;
+            throw err;
+        }
+    }
+
+    /**
+     * @method getMetaTag
+     * @description Fetches a page and returns the content of a specific meta tag.
+     * @param {string} url - The URL of the page to scrape.
+     * @param {string} metaName - The name attribute of the meta tag.
+     * @returns {Promise<string|null>} The content of the meta tag, or null if not found.
+     * @example
+     * const webname = await web.getMetaTag('https://client.example.com', 'webname');
+     */
+    public async getMetaTag(url: string, metaName: string): Promise<string | null> {
+        try {
+            const $ = await this.fetch(url);
+            return $(`meta[name="${metaName}"]`).attr('content') ?? null;
+        } catch (e) {
+            if (e instanceof TyrError) throw e;
+            throw new TyrError(`Could not read meta tag '${metaName}' from: ${url}`, e);
+        }
+    }
+
     /**
      * @method selectFromWeb
      * @description Selects elements from a web page using a CSS selector.

package/src/lib/WorkspaceManager.ts

@@ -0,0 +1,87 @@
+import { ShellManager } from './ShellManager.js';
+import { FileSystemManager } from './FileSystemManager.js';
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+
+/**
+ * @class WorkspaceManager
+ * @description Manages local workspace directories: checks for existing repos,
+ * creates branches and opens the project in VSCode.
+ */
+export class WorkspaceManager {
+    private shell: ShellManager;
+    private fs: FileSystemManager;
+    private logger: Logger;
+
+    constructor(shell: ShellManager, fs: FileSystemManager, logger: Logger) {
+        this.shell = shell;
+        this.fs = fs;
+        this.logger = logger;
+    }
+
+    /**
+     * @method checkExisting
+     * @description Checks whether a workspace directory already exists.
+     * If it does, asks the user if they want to replace it (deleting it first).
+     * Returns true if the caller should proceed with creating the workspace.
+     * @param {string} dirPath - Absolute path to the workspace directory.
+     * @param {string} type - Human-readable type name shown in messages (e.g. 'integración', 'web').
+     * @returns {Promise<boolean>} True if the workspace can be created/overwritten.
+     * @example
+     * const proceed = await workspace.checkExisting('/path/to/repo', 'integración');
+     * if (!proceed) return;
+     */
+    public async checkExisting(dirPath: string, type: string = 'directorio'): Promise<boolean> {
+        if (!this.fs.exists(dirPath)) return true;
+
+        this.logger.warn(`Este ${type} ya existe: ${dirPath}`);
+        const replace = await this.shell.confirm('¿Quieres reemplazarlo?', false);
+
+        if (!replace) {
+            this.logger.info('Operación cancelada.');
+            return false;
+        }
+
+        try {
+            await this.shell.exec(`rm -rf "${dirPath}"`);
+            this.logger.info('Directorio existente eliminado.');
+            return true;
+        } catch (e) {
+            throw new TyrError(`No se pudo eliminar el directorio existente: ${dirPath}`, e);
+        }
+    }
+
+    /**
+     * @method tagWorkspace
+     * @description Tags a workspace by creating and checking out a new Git branch,
+     * and optionally opening it in VSCode.
+     * @param {string} dir - Absolute path to the workspace directory.
+     * @param {string | null} branch - Branch name to create (null = skip branch creation).
+     * @param {boolean} openCode - Whether to open the directory in VSCode (default: true).
+     * @example
+     * await workspace.tagWorkspace('/path/to/repo', 'PROJ-123', true);
+     */
+    public async tagWorkspace(dir: string, branch: string | null, openCode: boolean = true): Promise<void> {
+        if (branch) {
+            try {
+                await this.shell.exec(`git -C "${dir}" checkout -b ${branch}`);
+                this.logger.success(`Rama '${branch}' creada.`);
+            } catch (e) {
+                this.logger.warn(`No se pudo crear la rama '${branch}'. Puede que ya exista.`);
+            }
+        }
+
+        if (openCode) {
+            try {
+                await this.shell.exec(`code "${dir}"`);
+            } catch {
+                this.logger.warn('No se pudo abrir VSCode. Asegúrate de tener el comando "code" instalado.');
+            }
+        }
+    }
+}
+
+export const WorkspaceManagerTests = {
+    checkExisting: { dirPath: '/tmp/tyr-workspace-test', type: 'integración' },
+    tagWorkspace: { dir: '/tmp/tyr-workspace-test', branch: null, openCode: false },
+};