meocord 3.1.0 → 3.2.0

package/dist/esm/bin/meocord.js

@@ -7,8 +7,9 @@ import { spawn } from 'node:child_process';
 import { capitalize } from 'lodash-es';
 import wait from '../util/wait.util.js';
 import { GeneratorCLI } from './generator.js';
+import { runtimePrefixFor, AppGeneratorHelper } from './helper/app-generator.helper.js';
 import * as fs from 'node:fs';
-import { setEnvironment, compileAndValidateConfig } from '../util/common.util.js';
+import { setEnvironment, compileAndValidateConfig, validateDiscordToken } from '../util/common.util.js';
 import { prepareModifiedTsConfig } from '../util/tsconfig.util.js';
 import { Command } from 'commander';
 import { simpleGit } from 'simple-git';
@@ -16,6 +17,8 @@ import { execSync } from 'child_process';
 import * as p from '@clack/prompts';
 import { detectInstalledPMs, getInstallCommand } from '../util/package-manager.util.js';
 import { ensureReady, configureCommandHelp } from '../util/meocord-cli.util.js';
+import { resolveOwnVersion } from '../util/package-version.util.js';
+import { buildAppCommand, resolveRuntime } from '../util/runtime.util.js';
 import packageJson from '../package.json.js';
 import { fileURLToPath } from 'url';
 import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
@@ -25,7 +28,35 @@ const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);
 /**
  * A Command Line Interface (CLI) for managing the MeoCord application.
- */ class MeoCordCLI {
+ */ /**
+ * Oldest Node the framework supports, mirroring `engines.node`.
+ *
+ * A test holds the two together, since a floor that drifted from the manifest would warn
+ * about versions npm is happy to install on.
+ */ const MINIMUM_NODE_MAJOR = 22;
+/**
+ * Warns when the running Node is older than the framework supports.
+ *
+ * Advisory only. Comparing against the newest LTS release meant warning about being a
+ * patch behind, and reaching the network to find out meant a failed request could stop
+ * the command outright — for a check whose only outcome is a warning.
+ */ function warnIfNodeIsBelowSupported() {
+    const major = Number.parseInt(process.versions.node.split('.')[0], 10);
+    if (Number.isFinite(major) && major < MINIMUM_NODE_MAJOR) {
+        p.log.warn(`Node ${process.versions.node} is older than the supported minimum (v${MINIMUM_NODE_MAJOR}). ` + `The app will be created, but may not run.`);
+    }
+}
+/**
+ * The package manager's own complaint, which `execSync` buries on the thrown object.
+ *
+ * Its `message` says only that a command exited non-zero, which is never the part worth
+ * reading.
+ */ function installFailure(error) {
+    const { stderr, message } = error ?? {};
+    const reported = stderr?.toString().trim();
+    return new Error(reported || message || String(error));
+}
+class MeoCordCLI {
     /**
    * Configures and runs the MeoCord CLI.
    */ async run() {
@@ -81,6 +112,9 @@ copies or substantial portions of the Software.
             if (options.build || options.dev) {
                 await compileAndValidateConfig();
             }
+            // Checked for every start, including one that skips the build: this is the point
+            // where the application actually needs to log in.
+            await validateDiscordToken();
             if (options.build) {
                 await this.build(mode);
                 await this.compileConfig();
@@ -94,7 +128,6 @@ copies or substantial portions of the Software.
     async createApp(appName, options) {
         const kebabCaseAppName = appName.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
         const appPath = path.resolve(process.cwd(), kebabCaseAppName);
-        const gitRepo = 'https://github.com/l7aromeo/meocord-template.git';
         p.intro(`meocord v${this.version}`);
         // Validate directory
         if (fs.existsSync(appPath)) {
@@ -102,24 +135,7 @@ copies or substantial portions of the Software.
             await wait(100);
             process.exit(1);
         }
-        let latestLTS = null;
-        try {
-            const res = await fetch('https://nodejs.org/dist/index.json');
-            const releases = await res.json();
-            const ltsRelease = releases.find((r)=>r.lts !== false);
-            if (ltsRelease) latestLTS = ltsRelease.version.slice(1);
-        } catch  {
-            p.cancel('No internet connection. Creating a MeoCord app requires network access.');
-            await wait(100);
-            process.exit(1);
-        }
-        if (latestLTS) {
-            const [major, minor, patch] = process.version.slice(1).split('.').map(Number);
-            const [minMajor, minMinor, minPatch] = latestLTS.split('.').map(Number);
-            if (major < minMajor || major === minMajor && minor < minMinor || major === minMajor && minor === minMinor && patch < minPatch) {
-                p.log.warn(`Your Node.js (${process.version}) is behind the latest LTS (v${latestLTS}). Consider upgrading for best compatibility.`);
-            }
-        }
+        warnIfNodeIsBelowSupported();
         // Determine package manager
         const installedPMs = detectInstalledPMs();
         let pm;
@@ -155,47 +171,42 @@ copies or substantial portions of the Software.
             pm = selected;
         }
         const s = p.spinner();
-        // Clone template
         s.start(`Creating a new MeoCord app: ${kebabCaseAppName}`);
         try {
-            await simpleGit().clone(gitRepo, appPath);
+            this.appGeneratorHelper.generateApp(appPath, {
+                appName: kebabCaseAppName,
+                displayName: appName,
+                version: this.version,
+                packageManager: pm,
+                runtimePrefix: runtimePrefixFor(pm)
+            });
         } catch (error) {
-            s.stop('Failed to fetch template.');
-            p.cancel(error instanceof Error ? error.message : String(error));
-            await wait(100);
-            process.exit(1);
+            s.stop('Failed to create the app.');
+            await this.abortCreate(appPath, error);
         }
         s.stop(`App created at: ${appPath}`);
-        // Initialize git
         s.start('Initializing Git repository...');
         try {
-            fs.rmSync(path.join(appPath, '.git'), {
-                recursive: true,
-                force: true
-            });
             const git = simpleGit(appPath);
             await git.init();
             await git.add('./*');
             await git.commit('Initial commit');
         } catch (error) {
             s.stop('Failed to initialize Git.');
-            p.cancel(error instanceof Error ? error.message : String(error));
-            await wait(100);
-            process.exit(1);
+            await this.abortCreate(appPath, error);
         }
         s.stop('Git repository initialized.');
-        // Install dependencies
         s.start(`Installing dependencies with ${pm}...`);
         try {
+            // Output is captured rather than discarded: a failed install is only actionable
+            // if the resolver's complaint survives to the error message.
             execSync(getInstallCommand(pm), {
                 cwd: appPath,
-                stdio: 'ignore'
+                stdio: 'pipe'
             });
         } catch (error) {
             s.stop('Failed to install dependencies.');
-            p.cancel(error instanceof Error ? error.message : String(error));
-            await wait(100);
-            process.exit(1);
+            await this.abortCreate(appPath, installFailure(error));
         }
         s.stop('Dependencies installed.');
         p.outro(`MeoCord app "${kebabCaseAppName}" is ready!`);
@@ -341,6 +352,40 @@ copies or substantial portions of the Software.
         }
     }
     /**
+   * Replaces the running application with one built from the current sources.
+   *
+   * The replacement is spawned only once the previous process has exited. Both would
+   * hold the same gateway session, and claiming it before the first lets go produces a
+   * login conflict rather than a reload.
+   */ restartApp() {
+        const previous = this.appProcess;
+        this.appProcess = null;
+        if (!previous || previous.killed) {
+            this.appProcess = this.spawnApp();
+            return;
+        }
+        previous.removeAllListeners('exit');
+        previous.once('exit', ()=>{
+            this.appProcess = this.spawnApp();
+        });
+        previous.kill();
+    }
+    /**
+   * Runs the built application.
+   *
+   * Shared by both start modes so watching and production launch the bundle the same
+   * way; a watcher that spawned it differently could pass in development and fail in
+   * production on the difference alone.
+   *
+   * @returns The application process.
+   */ spawnApp() {
+        const { command, args } = buildAppCommand(this.runtime, this.mainJSPath);
+        return spawn(command, args, {
+            cwd: this.projectRoot,
+            stdio: 'inherit'
+        });
+    }
+    /**
    * Starts the MeoCord application in development mode with live updates.
    */ async startDev() {
         try {
@@ -357,7 +402,6 @@ copies or substantial portions of the Software.
                 await wait(100);
                 process.exit(1);
             }
-            let nodemonProcess = null;
             let isRunning = false;
             const watch = ()=>compiler.watch({}, (err, stats)=>{
                     if (err) {
@@ -367,18 +411,7 @@ copies or substantial portions of the Software.
                     if (stats?.hasErrors()) {
                         this.logger.error('Build failed due to errors in the compilation process:', stats.compilation.errors);
                     } else {
-                        if (nodemonProcess) {
-                            nodemonProcess.kill();
-                            nodemonProcess = null;
-                        }
-                        nodemonProcess = spawn('npx -y nodemon', [
-                            '-q',
-                            this.mainJSPath
-                        ], {
-                            shell: true,
-                            cwd: this.projectRoot,
-                            stdio: 'inherit'
-                        });
+                        this.restartApp();
                         isRunning = true;
                     }
                 });
@@ -387,12 +420,12 @@ copies or substantial portions of the Software.
             const fsWatcher = fs.watch(path.resolve(process.cwd(), 'meocord.config.ts'), ()=>{
                 clearTimeout(debounceWatcher);
                 debounceWatcher = setTimeout(async ()=>{
-                    if (isRunning && nodemonProcess) {
+                    if (isRunning && this.appProcess) {
                         isRunning = false;
                         this.logger.log('MeoCord config change detected, reloading config...');
-                        if (nodemonProcess && !nodemonProcess.killed) {
-                            nodemonProcess.kill();
-                            nodemonProcess = null;
+                        if (this.appProcess && !this.appProcess.killed) {
+                            this.appProcess.kill();
+                            this.appProcess = null;
                         }
                         await new Promise((resolve)=>compiler.close(resolve));
                         watch();
@@ -403,15 +436,15 @@ copies or substantial portions of the Software.
             process.on('SIGINT', async ()=>{
                 if (sigintReceived) {
                     // Second Ctrl+C — force kill and exit immediately
-                    if (nodemonProcess && !nodemonProcess.killed) nodemonProcess.kill('SIGKILL');
+                    if (this.appProcess && !this.appProcess.killed) this.appProcess.kill('SIGKILL');
                     process.exit(1);
                 }
                 sigintReceived = true;
-                // Nodemon and the bot already received SIGINT from the process group.
-                // Clean up parent-owned resources and wait for nodemon to exit.
+                // The application already received SIGINT from the process group. Clean up
+                // parent-owned resources and wait for it to exit on its own terms.
                 fsWatcher.close();
-                if (nodemonProcess && !nodemonProcess.killed) {
-                    nodemonProcess.on('exit', async ()=>{
+                if (this.appProcess && !this.appProcess.killed) {
+                    this.appProcess.on('exit', async ()=>{
                         await new Promise((resolve)=>compiler.close(resolve));
                         process.exit(0);
                     });
@@ -436,11 +469,7 @@ copies or substantial portions of the Software.
             }
             this.clearConsole();
             this.logger.log('Starting...');
-            const start = spawn(`node ${this.mainJSPath}`, {
-                shell: true,
-                cwd: this.projectRoot,
-                stdio: 'inherit'
-            }).on('spawn', this.clearConsole);
+            const start = this.spawnApp().on('spawn', this.clearConsole);
             start.on('exit', (code)=>{
                 process.exit(code ?? 0);
             });
@@ -462,6 +491,20 @@ copies or substantial portions of the Software.
         }
     }
     /**
+   * Reports why creation failed and removes what was written.
+   *
+   * A directory left behind from a failed attempt is indistinguishable from one the user
+   * meant to keep, and the next attempt refuses to start because the name is taken.
+   */ async abortCreate(appPath, error) {
+        fs.rmSync(appPath, {
+            recursive: true,
+            force: true
+        });
+        p.cancel(error instanceof Error ? error.message : String(error));
+        await wait(100);
+        process.exit(1);
+    }
+    /**
    * Clears the console on all platforms.
    */ clearConsole() {
         process.stdout.write('\u001b[3J\u001b[2J\u001b[H');
@@ -473,13 +516,51 @@ copies or substantial portions of the Software.
         this.mainJSPath = path.join(this.projectRoot, 'dist', 'main.js');
         this.webpackConfigPath = path.resolve(__dirname$1, '..', '..', '..', 'webpack.config.js');
         this.generatorCLI = new GeneratorCLI(this.appName);
-        this.version = packageJson.version;
+        this.appGeneratorHelper = new AppGeneratorHelper();
+        this.version = resolveOwnVersion(__dirname$1, packageJson.version);
+        /**
+   * Binary the application is spawned with, so it runs on the same runtime as the CLI
+   * rather than on whichever one happens to be named in the source.
+   */ this.runtime = resolveRuntime(process.env, process.execPath);
+        /** The running application, while a watch session owns one. */ this.appProcess = null;
+    }
+}
+/**
+ * Whether this file is what the process was started with.
+ *
+ * The bin ships behind a `node_modules/.bin` symlink, so `argv[1]` is the link while
+ * `import.meta.url` is its target; the two only agree once the link is resolved.
+ * Anything undecidable counts as a launch, so the published CLI still starts in cases
+ * this cannot classify.
+ */ function isProcessEntry() {
+    const invoked = process.argv[1];
+    if (invoked === undefined) return true;
+    try {
+        return samePath(fs.realpathSync(invoked), __filename$1);
+    } catch  {
+        return true;
     }
 }
-// Create an instance of the CLI and run it
-const cli = new MeoCordCLI();
-cli.run().catch(async (error)=>{
-    cli.logger.error('Failed to initialize CLI:', error?.message || error);
-    await wait(100);
-    process.exit(1);
-});
+/**
+ * Whether two resolved paths name the same file.
+ *
+ * Windows paths differ in case and separator without naming different files — npm's
+ * shim passes the script path in whatever form it recorded — and a comparison that
+ * missed would leave the CLI exiting without a word, since it would decide it was
+ * merely being imported.
+ */ function samePath(left, right) {
+    const normalise = (value)=>process.platform === 'win32' ? path.resolve(value).toLowerCase() : value;
+    return normalise(left) === normalise(right);
+}
+// Importing this module must not launch the command parser: its own tests do exactly
+// that to inspect how the application is spawned.
+if (isProcessEntry()) {
+    const cli = new MeoCordCLI();
+    cli.run().catch(async (error)=>{
+        cli.logger.error('Failed to initialize CLI:', error?.message || error);
+        await wait(100);
+        process.exit(1);
+    });
+}
+
+export { MINIMUM_NODE_MAJOR, MeoCordCLI };

package/dist/esm/decorator/guard.decorator.js

@@ -99,7 +99,7 @@ export class ButtonInteractionGuard implements GuardInterface {
  * @example
  * ```typescript
  * // Method-level usage
- * @Command('profile-{id}', CommandType.BUTTON)
+ * @Command('profile/{id}', CommandType.BUTTON)
  * @UseGuard(
  *   { provide: RateLimiterGuard, params: { limit: 2, window: 3000 } },
  *   ButtonInteractionGuard

package/dist/esm/util/common.util.js

@@ -47,8 +47,16 @@ import chalk from 'chalk';
         await wait(100);
         process.exit(1);
     }
-    const meocordConfig = loadMeoCordConfig();
-    if (!meocordConfig?.discordToken) {
+    loadMeoCordConfig();
+}
+/**
+ * Ensures a Discord token is configured.
+ *
+ * Kept apart from {@link compileAndValidateConfig} because producing a bundle needs no
+ * credentials — only connecting to the gateway does. Requiring one to build meant a
+ * freshly created application could not be built until a token had been obtained.
+ */ async function validateDiscordToken() {
+    if (!loadMeoCordConfig()?.discordToken) {
         console.error(chalk.red('Discord token is missing!'));
         await wait(100);
         process.exit(1);
@@ -65,4 +73,4 @@ import chalk from 'chalk';
     }
 }
 
-export { compileAndValidateConfig, findModulePackageDir, setEnvironment };
+export { compileAndValidateConfig, findModulePackageDir, setEnvironment, validateDiscordToken };

package/dist/esm/util/generator-cli.util.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
 import { kebabCase, startCase, camelCase } from 'lodash-es';
@@ -67,12 +67,29 @@ const logger = new Logger('MeoCord');
  */ function generateFile(filePath, content) {
     try {
         fs.writeFileSync(filePath, content);
-        logger.log(`Guard file created at: ${path.relative(process.cwd(), filePath)}`);
-        exec(`npx eslint --fix ${filePath}`);
+        logger.log(`Created ${path.relative(process.cwd(), filePath)}`);
+        formatWithLocalESLint(filePath);
     } catch (error) {
-        logger.error(`Failed to create guard file at ${filePath}`, error);
+        logger.error(`Failed to create ${filePath}`, error);
     }
 }
+/**
+ * Formats a generated file with the project's own ESLint, when it has one.
+ *
+ * Reaching for `npx` instead would start downloading ESLint into a project that
+ * deliberately does not have it, once per generated file, with no way to see it happen —
+ * the call is not awaited. A project with its own rules still gets them applied.
+ */ function formatWithLocalESLint(filePath) {
+    const binary = path.resolve(process.cwd(), 'node_modules', '.bin', process.platform === 'win32' ? 'eslint.cmd' : 'eslint');
+    if (!fs.existsSync(binary)) return;
+    execFile(binary, [
+        '--fix',
+        filePath
+    ], ()=>{
+    // Formatting is a courtesy; a project whose rules reject the template should still
+    // end up with the file it asked for.
+    });
+}
 /**
  * Builds and returns a template string for a given class name using a specific template file.
  * @param className - The name of the class to insert into the template.

package/dist/esm/util/package-manager.util.js

@@ -6,10 +6,17 @@ const ALL_PACKAGE_MANAGERS = [
     'yarn',
     'pnpm'
 ];
-function detectInstalledPMs() {
+/**
+ * The package managers available on this machine.
+ *
+ * Each candidate is asked for its version rather than looked up with `which`: `which` is
+ * a separate binary that a minimal image need not carry, and it is absent on Windows
+ * entirely. Running the tool also answers the question actually being asked — whether it
+ * works — rather than whether something with that name sits on the path.
+ */ function detectInstalledPMs() {
     return ALL_PACKAGE_MANAGERS.filter((pm)=>{
         try {
-            execSync(`which ${pm}`, {
+            execSync(`${pm} --version`, {
                 stdio: 'ignore'
             });
             return true;

package/dist/esm/util/package-version.util.js

@@ -0,0 +1,32 @@
+import fs__default from 'node:fs';
+import path from 'node:path';
+
+/** The package this CLI ships in, which is where the walk below stops. */ const OWN_PACKAGE_NAME = 'meocord';
+/**
+ * The version recorded in the package this CLI ships in.
+ *
+ * Read at run time rather than compiled in. The release bumps the manifest after the
+ * bundle has already been built, so a version baked into the bundle is always the one
+ * from before the release that published it.
+ *
+ * The walk stops at the first manifest naming this package: the repository root when
+ * running from source, the installed package root when running from `dist`.
+ *
+ * @param startDir - Directory to walk up from.
+ * @param fallback - Returned when no manifest for this package can be read.
+ */ function resolveOwnVersion(startDir, fallback) {
+    let current = path.resolve(startDir);
+    while(true){
+        try {
+            const manifest = JSON.parse(fs__default.readFileSync(path.join(current, 'package.json'), 'utf8'));
+            if (manifest.name === OWN_PACKAGE_NAME && typeof manifest.version === 'string') return manifest.version;
+        } catch  {
+        // Nothing readable here; the next directory up may still hold the manifest.
+        }
+        const parent = path.dirname(current);
+        if (parent === current) return fallback;
+        current = parent;
+    }
+}
+
+export { resolveOwnVersion };

package/dist/esm/util/runtime.util.js

@@ -0,0 +1,72 @@
+/**
+ * MeoCord Framework
+ * Copyright (c) 2025 Ukasyah Rahmatullah Zada
+ * SPDX-License-Identifier: MIT
+ */ /**
+ * Environment variable that pins the binary the application is spawned with.
+ *
+ * An escape hatch for pinning a specific install, or for running the application under a
+ * different runtime than the CLI to compare behaviour. Unset is the normal case.
+ */ const RUNTIME_OVERRIDE_ENV = 'MEOCORD_RUNTIME';
+/**
+ * Runners that are themselves JavaScript runtimes.
+ *
+ * `npm_execpath` names the binary that launched the script. npm, pnpm and yarn set it to
+ * a `.js` file, which cannot run the application, so only the runners listed here are
+ * read as a runtime. An entry belongs here only once it has been checked against that
+ * runner's real environment, since guessing wrong means spawning something that cannot
+ * execute the bundle.
+ */ const RUNTIME_RUNNERS = new Set([
+    'bun'
+]);
+/**
+ * The runtime that launched the CLI, when the CLI is not itself running on it.
+ *
+ * `bun run` honours the bin's `#!/usr/bin/env node` shebang, so the CLI lands on node
+ * even though the user asked for bun. What they chose is still recoverable: bun sets
+ * `npm_config_user_agent` to `bun/<version> …` and `npm_execpath` to its own binary.
+ *
+ * @param env - Environment the CLI was launched with.
+ * @returns The launcher's binary, or `undefined` when it cannot run the application.
+ */ function launcherRuntime(env) {
+    const runner = env.npm_config_user_agent?.split('/')[0];
+    const launcher = env.npm_execpath?.trim();
+    if (runner === undefined || !launcher) return undefined;
+    return RUNTIME_RUNNERS.has(runner) ? launcher : undefined;
+}
+/**
+ * The binary the application should be spawned with.
+ *
+ * Follows the runtime the user chose rather than naming one. Someone who typed `bun`
+ * gets a bun process, and an image built on bun alone stays that way — pinning `node`
+ * would oblige them to install a second runtime beside the one they picked, or to
+ * remember `--bun` on every command.
+ *
+ * Preference runs from the most explicit signal to the least: an override, then the
+ * runner that launched the CLI, then the binary executing it.
+ *
+ * @param env - Environment the CLI was launched with.
+ * @param execPath - Binary executing the CLI, i.e. `process.execPath`.
+ * @returns The binary to spawn.
+ */ function resolveRuntime(env, execPath) {
+    const override = env[RUNTIME_OVERRIDE_ENV]?.trim();
+    // An override of only whitespace would spawn '' and fail with an ENOENT naming nothing,
+    // so it is treated as absent rather than passed through.
+    if (override) return override;
+    return launcherRuntime(env) ?? execPath;
+}
+/**
+ * Runs the built application directly.
+ *
+ * @param runtime - Binary to run the application with.
+ * @param mainJsPath - Absolute path to the built entry file.
+ */ function buildAppCommand(runtime, mainJsPath) {
+    return {
+        command: runtime,
+        args: [
+            mainJsPath
+        ]
+    };
+}
+
+export { RUNTIME_OVERRIDE_ENV, buildAppCommand, resolveRuntime };

package/dist/types/core/index.d.ts

@@ -52,8 +52,8 @@ declare class MeoCordApp {
      *
      * Built once and cached, so dispatch stays a single ordered walk with an early exit
      * rather than paying to rank anything per interaction. Ordering here is what lets
-     * `gi-profile-summary-{ownerId}-{uid}` keep the ids it owns when
-     * `gi-profile-{uuid}-{uid}` would also match them — without it, the winner would be
+     * `gi-profile/summary/{ownerId}/{uid}` keep the ids it owns when
+     * `gi-profile/{uuid}/{uid}` would also match them — without it, the winner would be
      * whichever controller happened to be registered first.
      */
     private componentRoutes?;

package/dist/types/decorator/index.d.ts

@@ -295,7 +295,7 @@ interface GuardWithParams {
  * @example
  * ```typescript
  * // Method-level usage
- * @Command('profile-{id}', CommandType.BUTTON)
+ * @Command('profile/{id}', CommandType.BUTTON)
  * @UseGuard(
  *   { provide: RateLimiterGuard, params: { limit: 2, window: 3000 } },
  *   ButtonInteractionGuard

package/dist/types/interface/index.d.ts

@@ -57,9 +57,11 @@ interface CommandMetadata<T extends string = string> {
     dynamicParams?: T[];
     /**
      * How specific this pattern is; higher wins when more than one route matches the
-     * same customId. A greedy parameter can overlap a more literal sibling —
-     * `gi-profile-{uuid:*}-{uid}` also matches an id meant for
-     * `gi-profile-summary-{ownerId}-{uid}` — so dispatch cannot rely on declaration order.
+     * same customId. A parameter takes whatever fills its segment, so a broad pattern can
+     * also match an id a more literal sibling owns — `gi-profile/{uuid}/{uid}` matches
+     * `gi-profile/summary/123/456` just as `gi-profile/summary/{ownerId}/{uid}` does — and
+     * ranking is what settles it, since declaration order would make the winner depend on
+     * file layout.
      */
     specificity?: number;
 }