@orxataguy/tyr 1.0.42 → 1.0.44

package/README.md

@@ -180,11 +180,14 @@ Third parties can distribute commands as a `manifest.json` — a flat JSON map o
 ```json
 {
   "deploy": "https://raw.githubusercontent.com/someuser/tyr-modules/main/deploy.tyr.ts",
-  "rollback": "https://raw.githubusercontent.com/someuser/tyr-modules/main/rollback.tyr.ts"
+  "rollback": "https://raw.githubusercontent.com/someuser/tyr-modules/main/rollback.tyr.ts",
+  "$env": "https://raw.githubusercontent.com/someuser/tyr-modules/main/.env.example"
 }
 ```
 
-Register one with `tyr --add`, which validates the manifest, records it in `~/.tyr/imported_modules.yaml`, and immediately downloads whatever commands are missing:
+`$env` is optional and reserved (`$` can never appear in a command name, so it never collides with one). If present, it's downloaded as `~/.tyr/<module-name>.env.example` — a template of whatever environment variables that module's commands expect. It follows the exact same install/skip/force-update rules as commands below, and `tyr --del <module-name>` removes it along with everything else that module owns.
+
+Register one with `tyr --add`, which validates the manifest, records it in `~/.tyr/imported_modules.yaml`, and immediately downloads whatever commands (and `$env`, if present) are missing:
 
 ```bash
 tyr --add https://raw.githubusercontent.com/someuser/tyr-modules/main/manifest.json my-module
@@ -194,8 +197,11 @@ tyr --add https://raw.githubusercontent.com/someuser/tyr-modules/main/manifest.j
 tyr --modules           # list registered modules
 tyr --modules sync      # re-check all registered manifests and install anything missing
 tyr --update            # git pull ~/.tyr (if linked) and force-refresh all imported commands
+tyr --del my-module     # unregister a module: removes its commands, map.yml entries and lock records
 ```
 
+`tyr --del <module-name>` is the counterpart to `--add` — it looks up every command the lockfile says that module owns, deletes the command file, drops it (and any alias pointing to it) from `map.yml`, clears its lockfile entry, and finally removes the module from `imported_modules.yaml`. Commands that aren't tracked as belonging to that module (hand-written, or now owned by a different module after a collision) are left untouched.
+
 Rules worth knowing:
 
 - A command name that already exists locally is never overwritten by a plain sync — only `tyr --update` (or `tyr --modules sync --force`) refreshes commands that were themselves installed by an import.
@@ -219,6 +225,7 @@ Commit and push it, and anyone can install your commands with `tyr --add <raw-ur
 - Requires a GitHub remote named `origin` — other hosts aren't supported, since the URLs only resolve through `raw.githubusercontent.com`.
 - If `~/.tyr` isn't a git repository (or has no `origin` remote), `--manifest` refuses and tells you why instead of generating a broken file.
 - Commands whose file lives outside `~/.tyr` (an absolute path elsewhere on disk) are skipped, since they can't be resolved to a URL in the repo.
+- If `~/.tyr/.env.example` exists, it's automatically included as `$env`, so whoever runs `tyr --add` on your manifest gets it as `<module-name>.env.example`.
 
 ### `tyr chat [directory] [--port <n>] [--split <0-1>]`
 

package/package.json

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

package/src/core/Kernel.ts

@@ -85,6 +85,7 @@ export class Kernel {
             console.log('       tyr --upgrade    Upgrade Tyr to the latest npm version');
             console.log('       tyr --modules    List or sync imported modules');
             console.log('       tyr --add <url>  Register and sync a manifest.json as an imported module');
+            console.log('       tyr --del <name> Unregister an imported module and remove its commands');
             console.log('       tyr --manifest   Generate ~/.tyr/manifest.json from your commands (requires a GitHub-linked repo)');
             return;
         }
@@ -194,6 +195,11 @@ export class Kernel {
             return;
         }
 
+        if (commandName === '--del') {
+            await modulesCommand(context)(['del', ...args.slice(1)]);
+            return;
+        }
+
         if (commandName === '--manifest') {
             await modulesCommand(context)(['manifest']);
             return;

package/src/core/sys/help.ts

@@ -76,6 +76,7 @@ export default function help({ userRoot }: TyrContext) {
             { name: '--upgrade', description: 'Upgrades the tyr npm package.',                usage: 'tyr --upgrade' },
             { name: '--modules', description: 'Lists or syncs modules imported via manifest.json.', usage: 'tyr --modules [sync|list]' },
             { name: '--add',     description: 'Registers a manifest.json URL as an imported module and syncs it.', usage: 'tyr --add <manifest-url> [name]' },
+            { name: '--del',     description: 'Unregisters an imported module and removes the commands it owns.', usage: 'tyr --del <module-name>' },
             { name: '--manifest', description: 'Generates ~/.tyr/manifest.json from your commands (needs a GitHub-linked repo).', usage: 'tyr --manifest' },
             { name: 'gen',       description: 'Generates a new command from a description using AI.', usage: 'tyr gen <name> "<description>"' },
             { name: 'doc',       description: 'Opens the framework documentation in the browser.', usage: 'tyr doc' },

package/src/core/sys/modules.ts

@@ -18,8 +18,15 @@ interface ManagedCommand {
     source: string;
 }
 
+interface ManagedEnvFile {
+    manifest: string;
+    source: string;
+    file: string;
+}
+
 interface ModulesLock {
     commands: Record<string, ManagedCommand>;
+    env?: Record<string, ManagedEnvFile>;
 }
 
 export interface SyncSummary {
@@ -41,8 +48,19 @@ function isValidHttpsUrl(value: string): boolean {
     }
 }
 
+// Allows namespaced command names like 'db:migrate', but not a leading/
+// trailing/doubled ':' (e.g. ':foo', 'foo:', 'a::b'), since those would
+// produce an empty segment.
 function isValidCommandName(name: string): boolean {
-    return /^[a-zA-Z0-9_-]+$/.test(name);
+    return /^[a-zA-Z0-9_-]+(:[a-zA-Z0-9_-]+)*$/.test(name);
+}
+
+// ':' is a valid character in a command name (namespacing, e.g. 'db:migrate')
+// but isn't a safe filename component on every platform (Windows reserves it).
+// Only used when deriving the on-disk file name — the real name with its
+// colons is still what's stored in map.yml, the lockfile, and the manifest.
+function toSafeFilename(commandName: string): string {
+    return commandName.replace(/:/g, '-');
 }
 
 function slugFromUrl(url: string): string {
@@ -71,12 +89,24 @@ async function saveYaml(fs: any, filePath: string, data: unknown): Promise<void>
     await fs.write(filePath, yaml.dump(data, { indent: 2, lineWidth: -1 }));
 }
 
+// Reserved manifest key for an optional .env.example reference. '$' can never
+// appear in a valid command name (see isValidCommandName), so it can't collide
+// with a real command.
+const ENV_MANIFEST_KEY = '$env';
+
+interface ParsedManifest {
+    commands: Record<string, string>;
+    envUrl?: string;
+}
+
 /**
  * Fetches a manifest.json (name -> raw file URL) and validates its shape.
  * Only https URLs and safe command names are accepted, to avoid path
  * traversal and to keep imported code coming from a known-good transport.
+ * A manifest may also carry a reserved `$env` key pointing at a raw
+ * .env.example file for the module's required environment variables.
  */
-async function fetchManifest(web: any, manifestUrl: string): Promise<Record<string, string>> {
+async function fetchManifest(web: any, manifestUrl: string): Promise<ParsedManifest> {
     if (!isValidHttpsUrl(manifestUrl)) {
         throw new TyrError(`Manifest URL must use https: ${manifestUrl}`);
     }
@@ -88,16 +118,28 @@ async function fetchManifest(web: any, manifestUrl: string): Promise<Record<stri
         throw new TyrError(`Manifest at ${manifestUrl} is not a valid JSON object.`);
     }
 
-    for (const [name, fileUrl] of Object.entries(parsed)) {
+    const commands: Record<string, string> = {};
+    let envUrl: string | undefined;
+
+    for (const [name, value] of Object.entries(parsed)) {
+        if (name === ENV_MANIFEST_KEY) {
+            if (typeof value !== 'string' || !isValidHttpsUrl(value)) {
+                throw new TyrError(`Manifest at ${manifestUrl} has an invalid (non-https) URL for '${ENV_MANIFEST_KEY}'.`);
+            }
+            envUrl = value;
+            continue;
+        }
+
         if (!isValidCommandName(name)) {
             throw new TyrError(`Manifest at ${manifestUrl} has an invalid command name: '${name}'`);
         }
-        if (typeof fileUrl !== 'string' || !isValidHttpsUrl(fileUrl)) {
+        if (typeof value !== 'string' || !isValidHttpsUrl(value)) {
             throw new TyrError(`Manifest at ${manifestUrl} has an invalid (non-https) URL for command '${name}'.`);
         }
+        commands[name] = value;
     }
 
-    return parsed as Record<string, string>;
+    return { commands, envUrl };
 }
 
 /**
@@ -134,6 +176,7 @@ export async function syncModules(context: TyrContext, options: { force?: boolea
 
     if (!mapConfig.commands) mapConfig.commands = {};
     if (!lock.commands) lock.commands = {};
+    if (!lock.env) lock.env = {};
 
     // Snapshot the state as it was *before* this run. Collisions between two
     // modules processed in the same run are resolved by processing order
@@ -149,9 +192,9 @@ export async function syncModules(context: TyrContext, options: { force?: boolea
     for (const [moduleName, manifestUrl] of Object.entries(modulesFile.modules ?? {})) {
         logger.info(`Syncing module '${moduleName}' (${manifestUrl})...`);
 
-        let manifest: Record<string, string>;
+        let parsedManifest: ParsedManifest;
         try {
-            manifest = await fetchManifest(web, manifestUrl);
+            parsedManifest = await fetchManifest(web, manifestUrl);
         } catch (e) {
             const reason = e instanceof Error ? e.message : String(e);
             logger.error(`Could not read manifest for module '${moduleName}': ${reason}`);
@@ -162,6 +205,8 @@ export async function syncModules(context: TyrContext, options: { force?: boolea
             continue;
         }
 
+        const { commands: manifest, envUrl } = parsedManifest;
+
         for (const [commandName, fileUrl] of Object.entries(manifest)) {
             const alreadyInMap = !!mapSnapshot[commandName];
             const managed = lockSnapshot[commandName];
@@ -183,14 +228,15 @@ export async function syncModules(context: TyrContext, options: { force?: boolea
                 const content = await web.get(fileUrl);
                 const fileContent = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
 
-                const destPath = path.join(userRoot, 'commands', `${commandName}.tyr.ts`);
+                const fileName = toSafeFilename(commandName);
+                const destPath = path.join(userRoot, 'commands', `${fileName}.tyr.ts`);
                 await fs.write(destPath, fileContent);
 
                 if (managed && managed.module !== moduleName) {
                     logger.warn(`'${commandName}' was previously managed by module '${managed.module}'; now owned by '${moduleName}'.`);
                 }
 
-                mapConfig.commands[commandName] = `./commands/${commandName}.tyr.ts`;
+                mapConfig.commands[commandName] = `./commands/${fileName}.tyr.ts`;
                 lock.commands[commandName] = { module: moduleName, manifest: manifestUrl, source: fileUrl };
                 mapChanged = true;
                 lockChanged = true;
@@ -209,6 +255,39 @@ export async function syncModules(context: TyrContext, options: { force?: boolea
                 summary.failed.push({ command: commandName, reason });
             }
         }
+
+        if (envUrl) {
+            const envFileName = `${moduleName}.env.example`;
+            const envDestPath = path.join(userRoot, envFileName);
+            const envManaged = lock.env![moduleName];
+
+            const shouldInstallEnv = !fs.exists(envDestPath);
+            const shouldForceUpdateEnv = force && !!envManaged;
+
+            if (!shouldInstallEnv && !shouldForceUpdateEnv) {
+                logger.info(
+                    envManaged
+                        ? `Skipping ${envFileName}: already installed. Use 'tyr --update' to refresh.`
+                        : `Skipping ${envFileName}: a file with that name already exists and isn't managed by an import.`
+                );
+            } else {
+                try {
+                    const envContent = await web.get(envUrl);
+                    const envFileContent = typeof envContent === 'string' ? envContent : JSON.stringify(envContent, null, 2);
+                    await fs.write(envDestPath, envFileContent);
+
+                    lock.env![moduleName] = { manifest: manifestUrl, source: envUrl, file: envFileName };
+                    lockChanged = true;
+
+                    logger.success(`${shouldInstallEnv ? 'Installed' : 'Updated'} ${envFileName} from module '${moduleName}'.`);
+                } catch (e) {
+                    const reason = e instanceof Error ? e.message : String(e);
+                    logger.error(`Could not download ${envFileName} for module '${moduleName}': ${reason}`);
+                    logger.info(`Could not download ${envFileName} for module '${moduleName}': ${reason}`);
+                    summary.failed.push({ command: envFileName, reason });
+                }
+            }
+        }
     }
 
     if (mapChanged) await saveYaml(fs, mapPath, mapConfig);
@@ -275,6 +354,104 @@ export async function addModule(context: TyrContext, manifestUrl: string, name?:
     await syncModules(context);
 }
 
+/**
+ * Unregisters a module: removes it from imported_modules.yaml, deletes every
+ * command file it's tracked as owning in the lockfile, drops those commands
+ * (and any aliases pointing at them) from map.yml, deletes its
+ * `<module>.env.example` if one was imported, and clears their lockfile
+ * entries. The counterpart to `tyr --add` — closes the loop.
+ */
+export async function removeModule(context: TyrContext, moduleName: string): Promise<void> {
+    const { logger, fs, userRoot } = context as any;
+
+    if (!moduleName) {
+        logger.error('Missing module name.');
+        logger.info('Usage: tyr --del <module-name>');
+        return;
+    }
+
+    const modulesPath = path.join(userRoot, IMPORTED_MODULES_FILE);
+    const mapPath = path.join(userRoot, 'map.yml');
+    const lockPath = path.join(userRoot, LOCK_FILE);
+
+    const modulesFile = await loadYaml<ImportedModulesFile>(fs, modulesPath, { modules: {} });
+    const mapConfig = await loadYaml<TyrConfig>(fs, mapPath, { commands: {} });
+    const lock = await loadYaml<ModulesLock>(fs, lockPath, { commands: {} });
+
+    if (!modulesFile.modules) modulesFile.modules = {};
+    if (!mapConfig.commands) mapConfig.commands = {};
+    if (!lock.commands) lock.commands = {};
+    if (!lock.env) lock.env = {};
+
+    const isRegistered = !!modulesFile.modules[moduleName];
+    const managedCommands = Object.entries(lock.commands)
+        .filter(([, info]) => info.module === moduleName)
+        .map(([commandName]) => commandName);
+    const managedEnv = lock.env[moduleName];
+
+    if (!isRegistered && managedCommands.length === 0 && !managedEnv) {
+        logger.error(`Module '${moduleName}' is not registered and owns no commands. Nothing to remove.`);
+        logger.info(`Module '${moduleName}' was not found in ${IMPORTED_MODULES_FILE} or ${LOCK_FILE}.`);
+        return;
+    }
+
+    let mapChanged = false;
+    let lockChanged = false;
+
+    for (const commandName of managedCommands) {
+        const scriptPath = mapConfig.commands[commandName];
+        if (scriptPath) {
+            const absolutePath = path.isAbsolute(scriptPath) ? scriptPath : path.resolve(userRoot, scriptPath);
+            if (fs.exists(absolutePath)) {
+                await fs.delete(absolutePath);
+            }
+            delete mapConfig.commands[commandName];
+            mapChanged = true;
+        }
+
+        if (mapConfig.aliases) {
+            for (const [alias, target] of Object.entries(mapConfig.aliases)) {
+                if (target === commandName) {
+                    delete mapConfig.aliases[alias];
+                    mapChanged = true;
+                    logger.info(`Alias '${alias}' removed (pointed to '${commandName}').`);
+                }
+            }
+        }
+
+        delete lock.commands[commandName];
+        lockChanged = true;
+
+        logger.success(`Removed command '${commandName}' (was managed by module '${moduleName}').`);
+    }
+
+    if (managedEnv) {
+        const envPath = path.join(userRoot, managedEnv.file);
+        if (fs.exists(envPath)) {
+            await fs.delete(envPath);
+        }
+        delete lock.env[moduleName];
+        lockChanged = true;
+        logger.success(`Removed ${managedEnv.file} (was managed by module '${moduleName}').`);
+    }
+
+    if (isRegistered) {
+        delete modulesFile.modules[moduleName];
+        await saveYaml(fs, modulesPath, modulesFile);
+    }
+
+    if (mapChanged) await saveYaml(fs, mapPath, mapConfig);
+    if (lockChanged) await saveYaml(fs, lockPath, lock);
+
+    const removedItems = [...managedCommands, ...(managedEnv ? [managedEnv.file] : [])];
+    const removedList = removedItems.length ? `: ${removedItems.join(', ')}` : '';
+    logger.success(
+        `Module '${moduleName}' removed` +
+        (removedItems.length ? ` — ${removedItems.length} item(s) removed${removedList}.` : ' (it had nothing managed).')
+    );
+    logger.info(`Module '${moduleName}' unlinked from ${IMPORTED_MODULES_FILE}${removedList}.`);
+}
+
 interface GithubRepoInfo {
     owner: string;
     repo: string;
@@ -306,6 +483,10 @@ function parseGithubRemote(remoteUrl: string): GithubRepoInfo | null {
  * the publishing counterpart of `tyr --add`: whatever this produces can be
  * handed to someone else, who registers it with `tyr --add <url>`.
  *
+ * If ~/.tyr/.env.example exists, its raw URL is also included under the
+ * reserved `$env` key, so `tyr --add` downloads it as `<module>.env.example`
+ * for whoever installs this manifest.
+ *
  * Requires ~/.tyr to be a git repository linked to a GitHub remote — there's
  * no way to build a raw.githubusercontent.com URL otherwise.
  */
@@ -371,16 +552,28 @@ export async function generateManifest(context: TyrContext): Promise<void> {
         manifest[name] = `https://raw.githubusercontent.com/${repoInfo.owner}/${repoInfo.repo}/${branch}/${normalized}`;
     }
 
-    if (Object.keys(manifest).length === 0) {
+    const commandCount = Object.keys(manifest).length;
+    if (commandCount === 0) {
         logger.info('No commands to include in manifest.json.');
     }
 
+    // If ~/.tyr has a .env.example, publish it too — tyr --add downloads it as
+    // <module>.env.example so whoever installs this manifest knows which
+    // environment variables these commands expect.
+    const envExamplePath = path.join(userRoot, '.env.example');
+    let includedEnv = false;
+    if (fs.exists(envExamplePath)) {
+        manifest[ENV_MANIFEST_KEY] = `https://raw.githubusercontent.com/${repoInfo.owner}/${repoInfo.repo}/${branch}/.env.example`;
+        includedEnv = true;
+    }
+
     const manifestPath = path.join(userRoot, 'manifest.json');
     await fs.write(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
 
     logger.success(
-        `manifest.json generated at ${manifestPath} (${Object.keys(manifest).length} commands` +
-        `${skipped.length ? `, ${skipped.length} skipped` : ''}).`
+        `manifest.json generated at ${manifestPath} (${commandCount} commands` +
+        `${skipped.length ? `, ${skipped.length} skipped` : ''}` +
+        `${includedEnv ? ', includes .env.example' : ''}).`
     );
     logger.info("Commit and push it so others can install it with: tyr --add <raw-url-to-manifest.json>");
 }
@@ -399,6 +592,10 @@ export default function modules(context: TyrContext) {
                 await addModule(context, args[1], args[2]);
                 return;
             }
+            case 'del': {
+                await removeModule(context, args[1]);
+                return;
+            }
             case 'manifest': {
                 await generateManifest(context);
                 return;
@@ -423,7 +620,7 @@ export default function modules(context: TyrContext) {
             }
             default:
                 logger.error(`Unknown subcommand '${sub}'.`);
-                logger.info('Usage: tyr --modules [sync|list|manifest]');
+                logger.info('Usage: tyr --modules [sync|list|manifest|del <module-name>]');
         }
     };
 }