@orxataguy/tyr 1.0.40 → 1.0.41

package/README.md

@@ -173,6 +173,53 @@ tyr doc
 # → Open http://localhost:3000
 ```
 
+### Imported modules
+
+Third parties can distribute commands as a `manifest.json` — a flat JSON map of command name to the raw URL of a `.tyr.ts` file:
+
+```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"
+}
+```
+
+Register one with `tyr --add`, which validates the manifest, records it in `~/.tyr/imported_modules.yml`, and immediately downloads whatever commands are missing:
+
+```bash
+tyr --add https://raw.githubusercontent.com/someuser/tyr-modules/main/manifest.json my-module
+```
+
+```bash
+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
+```
+
+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.
+- Hand-written commands are never touched, even if a manifest later defines a command with the same name.
+- If two modules define the same command name, the one processed last (last entry in `imported_modules.yml`) wins.
+- Only `https://` URLs are accepted, both for manifests and for the command files they point to.
+
+Which commands came from which module is tracked in `~/.tyr/imported_modules.lock.yml`, generated automatically — you shouldn't need to edit it by hand.
+
+#### Publishing your own modules
+
+If `~/.tyr` is linked to a GitHub repository (`tyr --config --repo <url>`), `tyr --manifest` generates `~/.tyr/manifest.json` for you, mapping every command in `map.yml` to its `raw.githubusercontent.com` URL on the current branch:
+
+```bash
+tyr --manifest
+# → ~/.tyr/manifest.json generated (2 commands)
+```
+
+Commit and push it, and anyone can install your commands with `tyr --add <raw-url-to-your-manifest.json>`. A few things to know:
+
+- 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.
+
 ### `tyr chat [directory] [--port <n>] [--split <0-1>]`
 
 Opens a local web app with a chat pane and a file browser for `directory` (defaults to the current directory). You can attach images to a message, drag the divider between the two panes to resize them, and click any file in the browser to preview it. Messages are answered by the configured AI vendor (see `AIVendorManager`, below) by default.

package/package.json

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

package/src/core/Kernel.ts

@@ -12,6 +12,7 @@ import doc from './sys/doc';
 import chat from './sys/chat';
 import config from './sys/config';
 import help from './sys/help';
+import modulesCommand, { syncModules } from './sys/modules';
 
 import { TyrError } from './TyrError';
 
@@ -80,8 +81,11 @@ export class Kernel {
             console.log('Usage: tyr <command> [args...]');
             console.log('       tyr --config     Configure Tyr for the first time');
             console.log('       tyr --version    Show version');
-            console.log('       tyr --update     Pull latest changes from the linked ~/.tyr repo');
+            console.log('       tyr --update     Pull latest changes from the linked ~/.tyr repo and refresh imported modules');
             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 --manifest   Generate ~/.tyr/manifest.json from your commands (requires a GitHub-linked repo)');
             return;
         }
 
@@ -95,15 +99,32 @@ export class Kernel {
         if (commandName === '--update') {
             const shell = this.container.get().shell;
             const gitDir = path.join(this.userRoot, '.git');
-            if (!fs.existsSync(gitDir)) {
-                console.log('~/.tyr is not linked to any git repository.');
+
+            if (fs.existsSync(gitDir)) {
+                console.log('Updating ~/.tyr from repository...');
+                shell.cd(this.userRoot);
+                await shell.exec('git pull');
+                console.log('Repository update complete.');
+            } else {
+                console.log('~/.tyr is not linked to any git repository. Skipping git pull.');
                 console.log('Run: tyr --config --repo <url>  to link it.');
-                return;
             }
-            console.log('Updating ~/.tyr from repository...');
-            shell.cd(this.userRoot);
-            await shell.exec('git pull');
-            console.log('Update complete.');
+
+            const modulesPath = path.join(this.userRoot, 'imported_modules.yml');
+            if (fs.existsSync(modulesPath)) {
+                console.log('\nUpdating imported modules...');
+                const updateContext = {
+                    ...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 syncModules(updateContext, { force: true });
+            }
+
             return;
         }
 
@@ -163,6 +184,21 @@ export class Kernel {
             return;
         }
 
+        if (commandName === '--modules') {
+            await modulesCommand(context)(args.slice(1));
+            return;
+        }
+
+        if (commandName === '--add') {
+            await modulesCommand(context)(['add', ...args.slice(1)]);
+            return;
+        }
+
+        if (commandName === '--manifest') {
+            await modulesCommand(context)(['manifest']);
+            return;
+        }
+
         const systemCommands: Record<string, CommandFactory> = {
             gen,
             rem,

package/src/core/sys/help.ts

@@ -72,8 +72,11 @@ export default function help({ userRoot }: TyrContext) {
             { name: '--help',    description: 'Shows this command listing.',                  usage: 'tyr --help' },
             { name: '--version', description: 'Shows the installed version of tyr.',          usage: 'tyr --version' },
             { name: '--config',  description: 'Configures tyr for the first time.',           usage: 'tyr --config' },
-            { name: '--update',  description: 'Updates ~/.tyr from the git repository.',      usage: 'tyr --update' },
+            { name: '--update',  description: 'Updates ~/.tyr from the git repository and refreshes imported modules.', usage: 'tyr --update' },
             { 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: '--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' },
             { name: 'chat',      description: 'Opens an AI chat + file browser for a directory.',  usage: 'tyr chat [directory] [--port <n>] [--split <0-1>]' },

package/src/core/sys/modules.ts

@@ -0,0 +1,414 @@
+import path from 'path';
+import yaml from 'js-yaml';
+import type { TyrContext } from '../Kernel';
+import { TyrError } from '../TyrError';
+
+interface TyrConfig {
+    commands: Record<string, string>;
+    aliases?: Record<string, string>;
+}
+
+interface ImportedModulesFile {
+    modules: Record<string, string>;
+}
+
+interface ManagedCommand {
+    module: string;
+    manifest: string;
+    source: string;
+}
+
+interface ModulesLock {
+    commands: Record<string, ManagedCommand>;
+}
+
+export interface SyncSummary {
+    installed: string[];
+    updated: string[];
+    skipped: string[];
+    failed: { command: string; reason: string }[];
+}
+
+const IMPORTED_MODULES_FILE = 'imported_modules.yml';
+const LOCK_FILE = 'imported_modules.lock.yml';
+
+function isValidHttpsUrl(value: string): boolean {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:';
+    } catch {
+        return false;
+    }
+}
+
+function isValidCommandName(name: string): boolean {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+function slugFromUrl(url: string): string {
+    try {
+        const parsed = new URL(url);
+        const base = parsed.pathname.split('/').filter(Boolean).pop() ?? 'module';
+        const withoutExt = base.replace(/\.json$/i, '').replace(/\.manifest$/i, '');
+        const slug = withoutExt.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+        return slug || 'module';
+    } catch {
+        return 'module';
+    }
+}
+
+async function loadYaml<T>(fs: any, filePath: string, fallback: T): Promise<T> {
+    const raw = await fs.read(filePath);
+    if (!raw) return fallback;
+    try {
+        return (yaml.load(raw) as T) ?? fallback;
+    } catch {
+        return fallback;
+    }
+}
+
+async function saveYaml(fs: any, filePath: string, data: unknown): Promise<void> {
+    await fs.write(filePath, yaml.dump(data, { indent: 2, lineWidth: -1 }));
+}
+
+/**
+ * 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.
+ */
+async function fetchManifest(web: any, manifestUrl: string): Promise<Record<string, string>> {
+    if (!isValidHttpsUrl(manifestUrl)) {
+        throw new TyrError(`Manifest URL must use https: ${manifestUrl}`);
+    }
+
+    const raw = await web.get(manifestUrl);
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new TyrError(`Manifest at ${manifestUrl} is not a valid JSON object.`);
+    }
+
+    for (const [name, fileUrl] of Object.entries(parsed)) {
+        if (!isValidCommandName(name)) {
+            throw new TyrError(`Manifest at ${manifestUrl} has an invalid command name: '${name}'`);
+        }
+        if (typeof fileUrl !== 'string' || !isValidHttpsUrl(fileUrl)) {
+            throw new TyrError(`Manifest at ${manifestUrl} has an invalid (non-https) URL for command '${name}'.`);
+        }
+    }
+
+    return parsed as Record<string, string>;
+}
+
+/**
+ * Reconciles ~/.tyr/imported_modules.yml against ~/.tyr/map.yml.
+ *
+ * - A command that doesn't exist yet in map.yml is installed.
+ * - A command that already exists and isn't tracked in the lockfile is left
+ *   untouched (it predates the import, or was hand-written).
+ * - A command tracked in the lockfile is only re-downloaded when `force` is
+ *   set (used by `tyr --update`), so day-to-day syncs never clobber content
+ *   silently.
+ * - If two modules define the same command name, the last one processed
+ *   wins (modules are processed in the order they appear in
+ *   imported_modules.yml).
+ */
+export async function syncModules(context: TyrContext, options: { force?: boolean } = {}): Promise<SyncSummary> {
+    const { logger, fs, web, userRoot } = context as any;
+    const force = options.force ?? false;
+
+    const summary: SyncSummary = { installed: [], updated: [], skipped: [], failed: [] };
+
+    const modulesPath = path.join(userRoot, IMPORTED_MODULES_FILE);
+    const mapPath = path.join(userRoot, 'map.yml');
+    const lockPath = path.join(userRoot, LOCK_FILE);
+
+    if (!fs.exists(modulesPath)) {
+        logger.info(`No ${IMPORTED_MODULES_FILE} found. Nothing to sync.`);
+        return summary;
+    }
+
+    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 (!mapConfig.commands) mapConfig.commands = {};
+    if (!lock.commands) lock.commands = {};
+
+    // Snapshot the state as it was *before* this run. Collisions between two
+    // modules processed in the same run are resolved by processing order
+    // (last one wins), independently of the --force flag; only commands that
+    // already existed prior to this run are subject to the install/skip/
+    // force-update rules below.
+    const mapSnapshot = { ...mapConfig.commands };
+    const lockSnapshot = { ...lock.commands };
+
+    let mapChanged = false;
+    let lockChanged = false;
+
+    for (const [moduleName, manifestUrl] of Object.entries(modulesFile.modules ?? {})) {
+        logger.info(`Syncing module '${moduleName}' (${manifestUrl})...`);
+
+        let manifest: Record<string, string>;
+        try {
+            manifest = 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}`);
+            summary.failed.push({ command: moduleName, reason });
+            continue;
+        }
+
+        for (const [commandName, fileUrl] of Object.entries(manifest)) {
+            const alreadyInMap = !!mapSnapshot[commandName];
+            const managed = lockSnapshot[commandName];
+
+            const shouldInstall = !alreadyInMap;
+            const shouldForceUpdate = force && !!managed;
+
+            if (!shouldInstall && !shouldForceUpdate) {
+                if (alreadyInMap && !managed) {
+                    logger.info(`Skipping '${commandName}': already exists and is not managed by an import.`);
+                } else {
+                    logger.info(`Skipping '${commandName}': already installed. Use 'tyr --update' to refresh.`);
+                }
+                summary.skipped.push(commandName);
+                continue;
+            }
+
+            try {
+                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`);
+                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`;
+                lock.commands[commandName] = { module: moduleName, manifest: manifestUrl, source: fileUrl };
+                mapChanged = true;
+                lockChanged = true;
+
+                if (shouldInstall) {
+                    logger.success(`Installed '${commandName}' from module '${moduleName}'.`);
+                    summary.installed.push(commandName);
+                } else {
+                    logger.success(`Updated '${commandName}' from module '${moduleName}'.`);
+                    summary.updated.push(commandName);
+                }
+            } catch (e) {
+                const reason = e instanceof Error ? e.message : String(e);
+                logger.error(`Could not download '${commandName}' from '${fileUrl}': ${reason}`);
+                summary.failed.push({ command: commandName, reason });
+            }
+        }
+    }
+
+    if (mapChanged) await saveYaml(fs, mapPath, mapConfig);
+    if (lockChanged) await saveYaml(fs, lockPath, lock);
+
+    logger.info(
+        `Sync finished — installed: ${summary.installed.length}, updated: ${summary.updated.length}, ` +
+        `skipped: ${summary.skipped.length}, failed: ${summary.failed.length}.`
+    );
+
+    return summary;
+}
+
+/**
+ * Registers a manifest URL under a module name in imported_modules.yml and
+ * immediately syncs it (downloads whatever commands are missing).
+ */
+export async function addModule(context: TyrContext, manifestUrl: string, name?: string): Promise<void> {
+    const { logger, fs, web, userRoot } = context as any;
+
+    if (!manifestUrl) {
+        logger.error('Missing manifest URL.');
+        logger.info('Usage: tyr --add <manifest-url> [name]');
+        return;
+    }
+
+    if (!isValidHttpsUrl(manifestUrl)) {
+        logger.error('Manifest URL must be a valid https:// URL.');
+        return;
+    }
+
+    logger.info(`Validating manifest: ${manifestUrl}`);
+    try {
+        await fetchManifest(web, manifestUrl);
+    } catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        logger.error(`Could not add module: ${reason}`);
+        return;
+    }
+
+    const moduleName = name && isValidCommandName(name) ? name : slugFromUrl(manifestUrl);
+
+    const modulesPath = path.join(userRoot, IMPORTED_MODULES_FILE);
+    const modulesFile = await loadYaml<ImportedModulesFile>(fs, modulesPath, { modules: {} });
+    if (!modulesFile.modules) modulesFile.modules = {};
+
+    if (modulesFile.modules[moduleName] && modulesFile.modules[moduleName] !== manifestUrl) {
+        logger.warn(`Module '${moduleName}' already pointed to a different manifest. Overwriting.`);
+    }
+
+    modulesFile.modules[moduleName] = manifestUrl;
+    await saveYaml(fs, modulesPath, modulesFile);
+    logger.success(`Module '${moduleName}' registered in ${modulesPath}`);
+
+    await syncModules(context);
+}
+
+interface GithubRepoInfo {
+    owner: string;
+    repo: string;
+}
+
+/**
+ * Parses the owner/repo out of a GitHub remote URL. Only github.com is
+ * supported, since manifest.json entries are meant to resolve through
+ * raw.githubusercontent.com.
+ */
+function parseGithubRemote(remoteUrl: string): GithubRepoInfo | null {
+    const patterns = [
+        /^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(\.git)?\/?$/,
+        /^git@github\.com:([^/]+)\/([^/]+?)(\.git)?$/,
+        /^ssh:\/\/git@github\.com\/([^/]+)\/([^/]+?)(\.git)?$/,
+    ];
+
+    for (const pattern of patterns) {
+        const match = remoteUrl.trim().match(pattern);
+        if (match) return { owner: match[1], repo: match[2] };
+    }
+
+    return null;
+}
+
+/**
+ * Generates ~/.tyr/manifest.json from the commands currently registered in
+ * map.yml, pointing each one at its raw.githubusercontent.com URL. This is
+ * the publishing counterpart of `tyr --add`: whatever this produces can be
+ * handed to someone else, who registers it with `tyr --add <url>`.
+ *
+ * Requires ~/.tyr to be a git repository linked to a GitHub remote — there's
+ * no way to build a raw.githubusercontent.com URL otherwise.
+ */
+export async function generateManifest(context: TyrContext): Promise<void> {
+    const { logger, fs, shell, userRoot } = context as any;
+
+    const gitDir = path.join(userRoot, '.git');
+    if (!fs.exists(gitDir)) {
+        logger.error('~/.tyr has no linked git repository. Cannot generate manifest.json.');
+        logger.info('Link one first: tyr --config --repo <url>');
+        return;
+    }
+
+    shell.cd(userRoot);
+
+    let remoteUrl: string;
+    try {
+        remoteUrl = await shell.exec('git remote get-url origin');
+    } catch {
+        logger.error("~/.tyr's repository has no 'origin' remote configured. Cannot generate manifest.json.");
+        return;
+    }
+
+    const repoInfo = parseGithubRemote(remoteUrl);
+    if (!repoInfo) {
+        logger.error(`Cannot generate manifest.json: only GitHub repositories are supported (raw.githubusercontent.com). Remote was: ${remoteUrl}`);
+        return;
+    }
+
+    let branch = 'main';
+    try {
+        const currentBranch = await shell.exec('git rev-parse --abbrev-ref HEAD');
+        if (currentBranch && currentBranch !== 'HEAD') {
+            branch = currentBranch;
+        } else {
+            logger.warn(`Could not determine the current branch (detached HEAD?). Falling back to '${branch}'.`);
+        }
+    } catch {
+        logger.warn(`Could not determine the current branch. Falling back to '${branch}'.`);
+    }
+
+    const mapPath = path.join(userRoot, 'map.yml');
+    const mapConfig = await loadYaml<TyrConfig>(fs, mapPath, { commands: {} });
+    const commands = mapConfig.commands ?? {};
+
+    const manifest: Record<string, string> = {};
+    const skipped: string[] = [];
+
+    for (const [name, scriptPath] of Object.entries(commands)) {
+        const repoRelativePath = path.isAbsolute(scriptPath)
+            ? path.relative(userRoot, scriptPath)
+            : scriptPath.replace(/^\.[/\\]/, '');
+
+        if (repoRelativePath.startsWith('..')) {
+            logger.warn(`Skipping '${name}': its file lives outside ~/.tyr and can't be published.`);
+            skipped.push(name);
+            continue;
+        }
+
+        const normalized = repoRelativePath.split(path.sep).join('/');
+        manifest[name] = `https://raw.githubusercontent.com/${repoInfo.owner}/${repoInfo.repo}/${branch}/${normalized}`;
+    }
+
+    if (Object.keys(manifest).length === 0) {
+        logger.warn('No commands to include in manifest.json.');
+    }
+
+    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` : ''}).`
+    );
+    logger.info("Commit and push it so others can install it with: tyr --add <raw-url-to-manifest.json>");
+}
+
+export default function modules(context: TyrContext) {
+    return async (args: string[]) => {
+        const { logger, fs, userRoot } = context as any;
+        const sub = args[0];
+
+        switch (sub) {
+            case 'sync': {
+                await syncModules(context, { force: args.includes('--force') });
+                return;
+            }
+            case 'add': {
+                await addModule(context, args[1], args[2]);
+                return;
+            }
+            case 'manifest': {
+                await generateManifest(context);
+                return;
+            }
+            case 'list':
+            case undefined: {
+                const modulesPath = path.join(userRoot, IMPORTED_MODULES_FILE);
+                const modulesFile = await loadYaml<ImportedModulesFile>(fs, modulesPath, { modules: {} });
+                const entries = Object.entries(modulesFile.modules ?? {});
+
+                if (entries.length === 0) {
+                    logger.info('No imported modules registered.');
+                    logger.info('Add one with: tyr --add <manifest-url> [name]');
+                    return;
+                }
+
+                logger.info('Imported modules:');
+                for (const [name, url] of entries) {
+                    logger.info(`  ${name} -> ${url}`);
+                }
+                return;
+            }
+            default:
+                logger.error(`Unknown subcommand '${sub}'.`);
+                logger.info('Usage: tyr --modules [sync|list|manifest]');
+        }
+    };
+}