@akira-tl/forgerelay 1.2.5 → 1.3.0

package/dist/cli/core/command-tree.js

@@ -0,0 +1,68 @@
+export const CLI_ROOT_ROUTES = [
+    { command: "serve", handler: "serve", publicSummary: "Start the ForgeRelay runtime" },
+    { command: "init", handler: "init", publicSummary: "Run first-time or setup-owned configuration" },
+    { command: "config", handler: "config", publicSummary: "Inspect and mutate declarative configuration" },
+    { command: "connect", handler: "connect", publicSummary: "Manage remote ForgeRelay and External MCP relationships" },
+    { command: "system", handler: "system", publicSummary: "Diagnose and maintain ForgeRelay" },
+    { command: "help", handler: "help", publicSummary: "Show this help" },
+    { command: "version", handler: "version", publicSummary: "Print the installed version" },
+    // Compatibility-only routes. These remain dispatchable during the supported
+    // compatibility window but never appear in generated public root help.
+    { command: "start", handler: "serve" },
+    { command: "doctor", handler: "system", argsPrefix: ["doctor"] },
+    { command: "hooks", handler: "config", argsPrefix: ["hooks", "--compat"] },
+    { command: "auth", handler: "connect", argsPrefix: ["relay"] },
+    { command: "mcp", handler: "connect", argsPrefix: ["mcp"] },
+    { command: "maintenance", handler: "system" },
+    { command: "agents", compatibilityHandler: "agents" },
+    { command: "--help", handler: "help" },
+    { command: "-h", handler: "help" },
+    { command: "--version", handler: "version" },
+    { command: "-v", handler: "version" },
+];
+export function resolveCliRootRoute(command) {
+    if (command === undefined)
+        return { command: "help", handler: "help" };
+    const route = CLI_ROOT_ROUTES.find((candidate) => candidate.command === command);
+    if (!route)
+        throw new Error(`Unknown command: ${command}`);
+    return route;
+}
+export function routeArguments(route, args) {
+    return [...(route.argsPrefix ?? []), ...args];
+}
+const SERVE_OPTION_HELP_LINES = [
+    "--host <host>             Override the bind host for this invocation",
+    "--port <port>             Override the listen port for this invocation",
+    "--root <path>             Override allowed roots; repeat for multiple roots",
+    "--public-url <url>        Override client-facing base URLs; repeat for multiple URLs",
+    "--allow-elevated          Explicitly allow this invocation to run with elevated/unknown OS privilege",
+];
+export function renderCliRootHelp() {
+    const publicRoutes = CLI_ROOT_ROUTES.filter((route) => route.publicSummary !== undefined);
+    const commandWidth = Math.max(...publicRoutes.map((route) => route.command.length));
+    return [
+        "ForgeRelay",
+        "",
+        "Usage:",
+        "  forgerelay                         Show help",
+        "  forgerelay <command> [options]     Run a command",
+        "",
+        "Commands:",
+        ...publicRoutes.map((route) => `  forgerelay ${route.command.padEnd(commandWidth)}  ${route.publicSummary}`),
+        "",
+        "Serve options:",
+        ...SERVE_OPTION_HELP_LINES.map((line) => `  forgerelay serve ${line}`),
+    ].join("\n");
+}
+export function renderServeHelp() {
+    return [
+        "ForgeRelay serve",
+        "",
+        "Usage:",
+        "  forgerelay serve [options]",
+        "",
+        "Options:",
+        ...SERVE_OPTION_HELP_LINES.map((line) => `  ${line}`),
+    ].join("\n");
+}

package/dist/cli/core/serve-options.js

@@ -0,0 +1,71 @@
+import { normalizeAllowedRootPath } from "../../runtime/config/validation/paths.js";
+import { normalizePublicBaseUrlsInput, validateBindAddress, validateClientFacingBaseUrls, validatePort, } from "../setup-support.js";
+export function parseServeCommandArgs(args) {
+    let allowElevated = false;
+    let host;
+    let port;
+    const roots = [];
+    const publicBaseUrls = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--allow-elevated") {
+            if (allowElevated)
+                throw new Error("--allow-elevated may only be supplied once.");
+            allowElevated = true;
+            continue;
+        }
+        if (arg === "--host") {
+            if (host !== undefined)
+                throw new Error("--host may only be supplied once.");
+            const value = args[++index];
+            if (value === undefined)
+                throw new Error("Missing value for --host.");
+            const validation = validateBindAddress(value);
+            if (validation)
+                throw new Error(`Invalid --host: ${validation}`);
+            host = value.trim();
+            continue;
+        }
+        if (arg === "--port") {
+            if (port !== undefined)
+                throw new Error("--port may only be supplied once.");
+            const value = args[++index];
+            if (value === undefined)
+                throw new Error("Missing value for --port.");
+            const validation = validatePort(value);
+            if (validation)
+                throw new Error(`Invalid --port: ${validation}`);
+            port = Number(value);
+            continue;
+        }
+        if (arg === "--root") {
+            const value = args[++index];
+            if (value === undefined)
+                throw new Error("Missing value for --root.");
+            roots.push(normalizeAllowedRootPath(value));
+            continue;
+        }
+        if (arg === "--public-url") {
+            const value = args[++index];
+            if (value === undefined)
+                throw new Error("Missing value for --public-url.");
+            const validation = validateClientFacingBaseUrls(value);
+            if (validation)
+                throw new Error(`Invalid --public-url: ${validation}`);
+            publicBaseUrls.push(...normalizePublicBaseUrlsInput(value));
+            continue;
+        }
+        throw new Error(`Unknown serve option: ${arg}`);
+    }
+    return {
+        allowElevated,
+        runtimeOverrides: {
+            ...(host === undefined ? {} : { host }),
+            ...(port === undefined ? {} : { port }),
+            ...(roots.length === 0 ? {} : { allowedRoots: roots }),
+            ...(publicBaseUrls.length === 0
+                ? {}
+                : { publicBaseUrl: Array.from(new Set(publicBaseUrls)) }),
+        },
+    };
+}

package/dist/cli/init/setup-config.js

@@ -1,3 +1,4 @@
+import { DEFAULT_INSTRUCTION_NAMES, DEFAULT_SKILL_PATHS, DEFAULT_SYSTEM_INSTRUCTIONS_PATH, } from "../../runtime/config/definition/general-config.js";
 export function applySetupConfig(current, selection) {
     const next = {
         ...current,
@@ -5,6 +6,8 @@ export function applySetupConfig(current, selection) {
         allowedRoots: [...selection.allowedRoots],
     };
     applyNetworkSelection(next, selection.network);
+    if (selection.context)
+        applyAgentContextSelection(next, selection.context);
     if (selection.advanced)
         applyAdvancedSelection(next, selection.advanced);
     return next;
@@ -22,6 +25,29 @@ function applyNetworkSelection(config, selection) {
         config.publicBaseUrl = selection.publicBaseUrl;
     }
 }
+function applyAgentContextSelection(config, selection) {
+    if (selection.systemInstructionsPath === DEFAULT_SYSTEM_INSTRUCTIONS_PATH) {
+        delete config.systemInstructionsPath;
+    }
+    else {
+        config.systemInstructionsPath = selection.systemInstructionsPath;
+    }
+    if (sameStringList(selection.instructionNames, DEFAULT_INSTRUCTION_NAMES)) {
+        delete config.instructionNames;
+    }
+    else {
+        config.instructionNames = [...selection.instructionNames];
+    }
+    if (sameStringList(selection.skillPaths, DEFAULT_SKILL_PATHS)) {
+        delete config.skillPaths;
+    }
+    else {
+        config.skillPaths = [...selection.skillPaths];
+    }
+}
+function sameStringList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 function applyAdvancedSelection(config, selection) {
     if (selection.port === 7676)
         delete config.port;

package/dist/cli/init.js

@@ -1,16 +1,21 @@
-import { resolve } from "node:path";
 import * as prompts from "@clack/prompts";
 import { publicEndpointUrl } from "../mcp/oauth/public-url.js";
-import { expandHomePath } from "../mcp/filesystem/roots.js";
+import { normalizeAllowedRootPaths } from "../runtime/config/validation/paths.js";
 import { detectLauncherCommandShell, } from "../runtime/shell/command-shell-runtime.js";
 import { seedShellInstructionFiles, shellInstructionFamiliesToSeed, } from "../runtime/instructions/shell-instructions.js";
 import { installManagedLanguageServers, installedManagedLanguageServers, managedLanguageServerOptions, } from "../lsp/runtime/managed-language-servers.js";
 import { generateInstanceId, generateOwnerToken, loadForgeRelayFiles, writeForgeRelayAuth, writeForgeRelayConfig, } from "../runtime/config/user-config.js";
-import { generalConfigDefinition } from "../runtime/config/definition/general-config.js";
+import { DEFAULT_INSTRUCTION_NAMES, DEFAULT_SKILL_PATHS, DEFAULT_SYSTEM_INSTRUCTIONS_PATH, generalConfigDefinition, } from "../runtime/config/definition/general-config.js";
 import { configSchemaId } from "../runtime/config/definition/schema.js";
 import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, SetupCancelledError, textPrompt, validateHttpsProxyBaseUrls, validateLanClientFacingBaseUrls, validatePort, } from "./setup-support.js";
 import { commandShellCompatibilityWarning, commandShellSetupOptions, customPinnedPreference, defaultCommandShellSetupChoice, followLauncherPreference, pinnedFamilyPreference, preservePinnedPreference, shellFamiliesForCustomSelection, } from "./shell/setup.js";
-import { applySetupConfig } from "./init/setup-config.js";
+import { applySetupConfig, } from "./init/setup-config.js";
+function parseSetupList(value) {
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+function validateSetupList(value) {
+    return value && parseSetupList(value).length > 0 ? undefined : "Enter at least one comma-separated value.";
+}
 export async function runInit({ force, advanced, version }) {
     const files = loadForgeRelayFiles();
     if (!force && !advanced && files.configExists && files.authExists) {
@@ -27,10 +32,33 @@ export async function runInit({ force, advanced, version }) {
             defaultValue: defaultRoots,
             validate: (value) => value?.trim() ? undefined : "Enter at least one project root.",
         });
-        const allowedRoots = rootsAnswer
-            .split(",")
-            .map((root) => resolve(expandHomePath(root.trim())))
-            .filter(Boolean);
+        const allowedRoots = normalizeAllowedRootPaths(rootsAnswer.split(","));
+        const defaultSystemInstructionsPath = files.config.systemInstructionsPath ?? DEFAULT_SYSTEM_INSTRUCTIONS_PATH;
+        const systemInstructionsPath = (await textPrompt({
+            message: `Which system instruction file should ForgeRelay load? Press Enter to use ${defaultSystemInstructionsPath}`,
+            placeholder: defaultSystemInstructionsPath,
+            defaultValue: defaultSystemInstructionsPath,
+            validate: (value) => value?.trim() ? undefined : "Enter an instruction file path.",
+        })).trim();
+        const defaultInstructionNames = (files.config.instructionNames ?? DEFAULT_INSTRUCTION_NAMES).join(", ");
+        const instructionNames = parseSetupList(await textPrompt({
+            message: `Which project instruction filenames should ForgeRelay discover? Press Enter to use ${defaultInstructionNames}`,
+            placeholder: defaultInstructionNames,
+            defaultValue: defaultInstructionNames,
+            validate: validateSetupList,
+        }));
+        const defaultSkillPaths = (files.config.skillPaths ?? DEFAULT_SKILL_PATHS).join(", ");
+        const skillPaths = parseSetupList(await textPrompt({
+            message: `Which Skill directories should ForgeRelay scan? Press Enter to use ${defaultSkillPaths}`,
+            placeholder: defaultSkillPaths,
+            defaultValue: defaultSkillPaths,
+            validate: validateSetupList,
+        }));
+        const contextSelection = {
+            systemInstructionsPath,
+            instructionNames,
+            skillPaths,
+        };
         const defaultPort = String(files.config.port ?? 7676);
         const port = advanced
             ? Number(await textPrompt({
@@ -231,6 +259,7 @@ export async function runInit({ force, advanced, version }) {
                 mode: networkMode,
                 ...(publicBaseUrl === undefined ? {} : { publicBaseUrl }),
             },
+            context: contextSelection,
             ...(advancedSelection ? { advanced: advancedSelection } : {}),
         });
         const auth = {

package/dist/cli/maintenance-prune.js

@@ -91,7 +91,7 @@ export function pruneMaintenanceState(stateDir, policy, now = new Date()) {
     }
 }
 export function printMaintenancePruneReport(report) {
-    console.log("ForgeRelay maintenance prune");
+    console.log("ForgeRelay system prune");
     console.log(`State directory: ${report.stateDir}`);
     console.log(`Historical retention: ${report.historicalAuthorized ? `authorized before ${report.cutoff}` : "not authorized (unlimited)"}`);
     console.log(`Orphan administrative cleanup: ${report.administrativeAuthorized ? "authorized" : "not authorized"}`);

package/dist/cli/maintenance.js

@@ -23,12 +23,12 @@ export function runMaintenanceCommand(args, env = process.env) {
         return;
     }
     if (subcommand !== "inspect" && subcommand !== "prune") {
-        throw new Error(`Unknown maintenance command: ${subcommand}`);
+        throw new Error(`Unknown system maintenance command: ${subcommand}`);
     }
     const json = rest.includes("--json");
     const unknown = rest.filter((value) => value !== "--json");
     if (unknown.length > 0)
-        throw new Error(`Unknown maintenance ${subcommand} option: ${unknown[0]}`);
+        throw new Error(`Unknown system ${subcommand} option: ${unknown[0]}`);
     const inspection = inspectMaintenanceState(env);
     if (subcommand === "inspect") {
         if (json) {
@@ -567,7 +567,7 @@ function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function printMaintenanceReport(report) {
-    console.log(`ForgeRelay maintenance inspection`);
+    console.log(`ForgeRelay system inspection`);
     console.log(`State directory: ${report.stateDir}`);
     console.log(`Database: ${report.database}`);
     console.log(`Retention: durable history ${report.policy.durableHistory}; orphaned administrative cleanup ${report.policy.orphanedAdministrativeState ? "enabled" : "disabled"}`);
@@ -595,11 +595,11 @@ function formatBytes(bytes) {
 }
 function printMaintenanceHelp() {
     console.log([
-        "ForgeRelay maintenance",
+        "ForgeRelay system",
         "",
         "Usage:",
-        "  forgerelay maintenance inspect [--json]",
-        "  forgerelay maintenance prune [--json]",
+        "  forgerelay system inspect [--json]",
+        "  forgerelay system prune [--json]",
         "",
         "Inspection is read-only. Durable history is retained without an age limit unless retention.historyDays is explicitly configured.",
         "Prune is manual owner maintenance and removes only categories authorized by the configured retention policy.",

package/dist/cli/mcp/external-mcp.js

@@ -6,14 +6,17 @@ import { computeScopeUnion, selectClientAuthMethod, } from "@modelcontextprotoco
 import { externalMcpCredentialIdentity, } from "../../runtime/config/external-mcp-auth-store.js";
 import { ExternalMcpInteractiveOAuthProvider, beginExternalMcpInteractiveOAuth, finishExternalMcpInteractiveOAuth, } from "../../mcp/operations/external-mcp/external-mcp-oauth.js";
 import { ExternalMcpError, ExternalMcpGateway, } from "../../mcp/operations/external-mcp/external-mcp.js";
-import { findExternalMcpServerStatus, formatAuth, formatExternalMcpList, inspectExternalMcpStatus, resolveExternalMcpScope, } from "./status.js";
+import { findExternalMcpServerStatus, formatAuth, formatExternalMcpStatus, inspectExternalMcpStatus, resolveExternalMcpScope, } from "./status.js";
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1_000;
 export async function runExternalMcpCommand(args, dependencies = {}) {
     const [subcommand, ...rest] = args;
     switch (subcommand) {
+        case "status":
+            await runExternalMcpStatus(parseMcpScopeArgs("status", rest), dependencies);
+            return;
         case "list":
         case "ls":
-            await runExternalMcpList(parseMcpScopeArgs("list", rest), dependencies);
+            await runExternalMcpStatus(parseMcpScopeArgs("list", rest), dependencies);
             return;
         case "test":
             await runExternalMcpTest(parseMcpTargetArgs("test", rest), dependencies);
@@ -31,7 +34,7 @@ export async function runExternalMcpCommand(args, dependencies = {}) {
             printMcpHelp();
             return;
         default:
-            throw new Error(`Unknown mcp command: ${subcommand}`);
+            throw new Error(`Unknown connect mcp command: ${subcommand}`);
     }
 }
 function parseMcpScopeArgs(command, args) {
@@ -51,7 +54,7 @@ function parseMcpScopeArgs(command, args) {
             continue;
         }
         if (arg.startsWith("-"))
-            throw new Error(`Unknown mcp ${command} option: ${arg}`);
+            throw new Error(`Unknown connect mcp ${command} option: ${arg}`);
         rest.push(arg);
     }
     if (global && projectRoot)
@@ -65,7 +68,7 @@ function parseMcpScopeArgs(command, args) {
 function parseMcpTargetArgs(command, args) {
     const parsed = parseMcpScopeArgs(command, args);
     if (parsed.rest.length !== 1) {
-        throw new Error(`Usage: forgerelay mcp ${command} <server> [--project <path>|--global]`);
+        throw new Error(`Usage: forgerelay connect mcp ${command} <server> [--project <path>|--global]`);
     }
     return {
         server: parsed.rest[0],
@@ -73,13 +76,22 @@ function parseMcpTargetArgs(command, args) {
         ...(parsed.global ? { global: true } : {}),
     };
 }
-async function runExternalMcpList(options, dependencies) {
-    if (options.rest.length > 0) {
-        throw new Error("Usage: forgerelay mcp list [--project <path>|--global]");
+async function runExternalMcpStatus(options, dependencies) {
+    if (options.rest.length > 1) {
+        throw new Error("Usage: forgerelay connect mcp status [server] [--project <path>|--global]");
     }
     const scope = await resolveExternalMcpScope(options, dependencies);
     const status = inspectExternalMcpStatus(scope);
-    console.log(formatExternalMcpList(status));
+    const serverName = options.rest[0];
+    if (serverName) {
+        const server = findExternalMcpServerStatus(status, serverName);
+        if (!server)
+            throw new Error(`Unknown configured External MCP server: ${serverName}.`);
+        console.log(formatExternalMcpStatus({ ...status, servers: [server] }));
+    }
+    else {
+        console.log(formatExternalMcpStatus(status));
+    }
     if (status.configIssues > 0) {
         throw new Error("External MCP configuration or credential status contains issues.");
     }
@@ -144,8 +156,8 @@ function printTestTarget(scope, server) {
 }
 function externalMcpAuthCommand(scope, server) {
     return scope.mode === "global"
-        ? `forgerelay mcp auth ${cliArgument(server)} --global`
-        : `forgerelay mcp auth ${cliArgument(server)} --project ${cliArgument(scope.projectRoot)}`;
+        ? `forgerelay connect mcp auth ${cliArgument(server)} --global`
+        : `forgerelay connect mcp auth ${cliArgument(server)} --project ${cliArgument(scope.projectRoot)}`;
 }
 function cliArgument(value) {
     return /^[A-Za-z0-9_./:\\-]+$/.test(value) ? value : JSON.stringify(value);
@@ -340,7 +352,7 @@ function hasStaticAuthorizationHeader(headers) {
 function assertInteractive(dependencies) {
     const interactive = dependencies.isInteractive ?? (Boolean(input.isTTY) && Boolean(output.isTTY));
     if (!interactive) {
-        throw new Error("forgerelay mcp auth requires an interactive terminal for browser/callback authorization.");
+        throw new Error("forgerelay connect mcp auth requires an interactive terminal for browser/callback authorization.");
     }
 }
 async function promptMaskedCallback(dependencies) {
@@ -474,12 +486,12 @@ function isHeadlessEnvironment(env) {
 }
 function printMcpHelp() {
     console.log([
-        "ForgeRelay mcp",
+        "ForgeRelay connect mcp",
         "",
         "Usage:",
-        "  forgerelay mcp list [--project <path>|--global]",
-        "  forgerelay mcp test <server> [--project <path>|--global]",
-        "  forgerelay mcp auth <server> [--project <path>|--global]",
-        "  forgerelay mcp logout <server> [--project <path>|--global]",
+        "  forgerelay connect mcp status [server] [--project <path>|--global]",
+        "  forgerelay connect mcp test <server> [--project <path>|--global]",
+        "  forgerelay connect mcp auth <server> [--project <path>|--global]",
+        "  forgerelay connect mcp logout <server> [--project <path>|--global]",
     ].join("\n"));
 }

package/dist/cli/mcp/status.js

@@ -72,7 +72,7 @@ export function inspectExternalMcpStatus(scope) {
 export function findExternalMcpServerStatus(status, name) {
     return status.servers.find((server) => server.name === name);
 }
-export function formatExternalMcpList(status) {
+export function formatExternalMcpStatus(status) {
     const lines = ["External MCP", ""];
     if (status.scope.mode === "global") {
         lines.push("Scope: global");
@@ -147,7 +147,7 @@ export function formatExternalMcpDoctor(status) {
         `  Credential store: ${status.credentialStore}`,
         `  Config issues: ${status.configIssues}`,
         "  Hot reload: active",
-        "  Active checks: not run (use `forgerelay mcp test <server>`)",
+        "  Active checks: not run (use `forgerelay connect mcp test <server>`)",
     ].join("\n");
 }
 export function formatAuth(status) {

package/dist/cli/system/status.js

@@ -0,0 +1,35 @@
+import { resolveRuntimeConfigFacts } from "../../runtime/config/config.js";
+import { inspectRuntimeLease } from "../../runtime/state/runtime-lease.js";
+export function inspectSystemStatus(env = process.env) {
+    const config = resolveRuntimeConfigFacts(env);
+    return {
+        ...(config.instanceId ? { instanceId: config.instanceId } : {}),
+        stateDir: config.stateDir,
+        host: config.host,
+        port: config.port,
+        publicBaseUrl: config.publicBaseUrl,
+        lease: inspectRuntimeLease(config.stateDir),
+    };
+}
+export function runSystemStatus(env = process.env) {
+    const status = inspectSystemStatus(env);
+    console.log([
+        "ForgeRelay system status",
+        "",
+        `Instance: ${status.instanceId ?? "not initialized"}`,
+        `Runtime: ${formatRuntimeState(status.lease)}`,
+        ...(status.lease.pid === undefined ? [] : [`PID: ${status.lease.pid}`]),
+        `State dir: ${status.stateDir}`,
+        `Configured bind: ${status.host}:${status.port}`,
+        `Configured public URL: ${status.publicBaseUrl}`,
+    ].join("\n"));
+}
+function formatRuntimeState(lease) {
+    if (lease.malformed)
+        return "unknown (malformed runtime lease)";
+    if (lease.active)
+        return "running";
+    if (lease.stale)
+        return "not running (stale runtime lease present)";
+    return "not running";
+}