@akira-tl/forgerelay 1.1.2 → 1.2.0

package/dist/runtime/config/config.js

@@ -2,25 +2,18 @@ import { isIP } from "node:net";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandHomePath } from "../../mcp/filesystem/roots.js";
-import { mergeHookConfigs, parseHookConfig } from "../../mcp/hooks/hooks.js";
-import { forgerelayAgentsDir, forgerelaySkillsDir, generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
-import { parseExternalMcpServers, } from "./external-mcp-config.js";
+import { forgerelaySkillsDir, generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
 import { DEFAULT_MEDIA_MAX_BYTES } from "../../mcp/operations/media-content.js";
 import { shellInstructionPath } from "../instructions/shell-instructions.js";
 import { resolveConfiguredCommandShellRuntime, } from "../shell/command-shell-runtime.js";
+import { generalConfigDefinition } from "./definition/general-config.js";
+import { resolveGeneralConfig } from "./resolution/general.js";
+import { assertConfigResolutionValid } from "./resolution/resolver.js";
+import { ConfigRuntime } from "./runtime/config-runtime.js";
 const DEFAULT_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 const DEFAULT_ARTIFACT_MAX_FILE_BYTES = 100 * 1024 * 1024;
 const DEFAULT_TASK_REMINDER_INTERVAL = 30;
-function parsePort(value) {
-    if (value === undefined || value === "")
-        return 7676;
-    const port = Number(value);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error(`Invalid PORT: ${value}`);
-    }
-    return port;
-}
 function parseAllowedRoots(value) {
     if (Array.isArray(value)) {
         const roots = value.map((entry) => entry.trim()).filter(Boolean);
@@ -114,15 +107,6 @@ function parsePositiveInteger(value, fallback, name, max = Number.MAX_SAFE_INTEG
     }
     return parsed;
 }
-function parseNonNegativeInteger(value, fallback, name) {
-    if (value === undefined || value === "")
-        return fallback;
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed < 0 || parsed > Number.MAX_SAFE_INTEGER) {
-        throw new Error(`Invalid ${name}: ${value}`);
-    }
-    return parsed;
-}
 function parseLoggingConfig(env, trustProxy) {
     const format = parseLogFormat(productEnv(env, "LOG_FORMAT"));
     const requests = productEnv(env, "LOG_REQUESTS");
@@ -148,8 +132,7 @@ function resolveProxyTrust(env, config, host, publicBaseUrl) {
         }
         return ["loopback"];
     }
-    const envTrustedProxies = productEnv(env, "TRUSTED_PROXIES");
-    const explicitTrustedProxies = parseTrustedProxies(envTrustedProxies === undefined ? config.trustedProxies : envTrustedProxies);
+    const explicitTrustedProxies = parseTrustedProxies(config.trustedProxies);
     if (explicitTrustedProxies !== undefined)
         return explicitTrustedProxies;
     return isLoopbackHost(host) && !isLoopbackHost(new URL(publicBaseUrl).hostname)
@@ -253,81 +236,176 @@ function parsePublicBaseUrls(value, fallback) {
     const normalized = (raw ?? fallback).map((entry) => parsePublicBaseUrl(entry));
     return Array.from(new Set(normalized));
 }
-function resolvePublicDeployment(env, fileConfig, host, port) {
+function resolvePublicDeployment(configuredValue, host, port) {
     const localBaseUrls = [parsePublicBaseUrl(localPublicBaseUrl(host, port))];
-    const envBaseUrl = productEnv(env, "PUBLIC_BASE_URL");
-    const baseUrls = envBaseUrl !== undefined
-        ? parsePublicBaseUrls(envBaseUrl, localBaseUrls)
-        : parsePublicBaseUrls(fileConfig.publicBaseUrl, localBaseUrls);
+    const baseUrls = parsePublicBaseUrls(configuredValue, localBaseUrls);
     return {
         baseUrls,
         canonicalBaseUrl: baseUrls[0],
     };
 }
-export function loadConfig(env = process.env) {
+export function loadConfig(env = process.env, options = {}) {
+    const configRuntime = new ConfigRuntime();
+    const runtimeEnvironment = generalConfigRuntimeEnvironment(env);
+    configRuntime.captureResolutionInputs(generalConfigDefinition.domain, {
+        environment: runtimeEnvironment,
+        ...(options.runtimeOverrides ? { cli: options.runtimeOverrides } : {}),
+    });
     const files = loadForgeRelayFiles(env);
+    const generalResolution = resolveGeneralConfig({
+        env,
+        ...(options.runtimeOverrides ? { cli: options.runtimeOverrides } : {}),
+        ...(files.configExists ? { user: files.config, userSourcePath: files.configPath } : {}),
+        ...(options.projectConfig !== undefined
+            ? { project: options.projectConfig, projectSourcePath: options.projectConfigPath }
+            : {}),
+        ...(options.projectLocalConfig !== undefined
+            ? { projectLocal: options.projectLocalConfig, projectLocalSourcePath: options.projectLocalConfigPath }
+            : {}),
+    });
+    assertConfigResolutionValid(generalResolution);
+    const config = generalResolution.values;
+    refreshGeneralUserConfigSource(configRuntime, files.configPath, runtimeEnvironment);
     const instanceId = files.auth.instanceId?.trim() || generateInstanceId();
-    const host = env.HOST ?? files.config.host ?? "127.0.0.1";
-    const port = parsePort(env.PORT ?? files.config.port);
-    const publicDeployment = resolvePublicDeployment(env, files.config, host, port);
+    const host = config.host ?? "127.0.0.1";
+    const port = config.port ?? 7676;
+    const publicDeployment = resolvePublicDeployment(config.publicBaseUrl, host, port);
     const publicBaseUrl = publicDeployment.canonicalBaseUrl;
-    const proxyTrust = resolveProxyTrust(env, files.config, host, publicBaseUrl);
-    const commandShellRuntime = resolveConfiguredCommandShellRuntime(files.config.commandShell, process.platform, env);
+    const proxyTrust = resolveProxyTrust(env, config, host, publicBaseUrl);
+    const commandShellRuntime = resolveConfiguredCommandShellRuntime(config.commandShell, process.platform, env);
     const derivedAllowedHosts = [
         "localhost",
         "127.0.0.1",
         "::1",
         host,
         ...publicDeployment.baseUrls.map((baseUrl) => new URL(baseUrl).hostname),
-        ...(files.config.allowedHosts ?? []),
+        ...(config.allowedHosts ?? []),
     ];
-    return {
+    const serverConfig = {
+        configRuntime,
         instanceId,
         configDir: files.dir,
         host,
         port,
         oauth: parseOAuthConfig(env, files.auth.ownerToken),
-        allowedRoots: parseAllowedRoots(productEnv(env, "ALLOWED_ROOTS") ?? files.config.allowedRoots),
-        allowedHosts: parseAllowedHosts(productEnv(env, "ALLOWED_HOSTS"), derivedAllowedHosts),
+        allowedRoots: parseAllowedRoots(config.allowedRoots),
+        allowedHosts: parseAllowedHosts(config.allowedHosts, derivedAllowedHosts),
         publicBaseUrl,
         publicBaseUrls: publicDeployment.baseUrls,
         proxyTrust,
         toolMode: parseToolMode(env),
-        workflowInstructions: parseWorkflowInstructions(productEnv(env, "WORKFLOW_INSTRUCTIONS"), files.config.workflowInstructions),
-        appendInstructions: parseAppendInstructions(productEnv(env, "APPEND_INSTRUCTIONS"), files.config.appendInstructions),
+        workflowInstructions: parseWorkflowInstructions(undefined, config.workflowInstructions),
+        appendInstructions: parseAppendInstructions(undefined, config.appendInstructions),
         widgets: parseWidgetMode(productEnv(env, "WIDGETS")),
-        activityPanelExpanded: productEnv(env, "ACTIVITY_PANEL_EXPANDED") === undefined
-            ? files.config.activityPanelExpanded === true
-            : parseBoolean(productEnv(env, "ACTIVITY_PANEL_EXPANDED")),
-        stateDir: resolve(expandHomePath(productEnv(env, "STATE_DIR") ?? files.config.stateDir ?? defaultStateDir())),
-        worktreeRoot: resolve(expandHomePath(productEnv(env, "WORKTREE_ROOT") ?? files.config.worktreeRoot ?? defaultWorktreeRoot())),
-        artifactsEnabled: productEnv(env, "ARTIFACTS") === undefined
-            ? files.config.artifactsEnabled === true
-            : parseBoolean(productEnv(env, "ARTIFACTS")),
-        artifactMaxFileBytes: parsePositiveInteger(productEnv(env, "ARTIFACT_MAX_FILE_BYTES") ?? numberConfigValue(files.config.artifactMaxFileBytes), DEFAULT_ARTIFACT_MAX_FILE_BYTES, "FORGERELAY_ARTIFACT_MAX_FILE_BYTES"),
-        mediaMaxBytes: parsePositiveInteger(productEnv(env, "MEDIA_MAX_BYTES") ?? numberConfigValue(files.config.mediaMaxBytes), DEFAULT_MEDIA_MAX_BYTES, "FORGERELAY_MEDIA_MAX_BYTES"),
-        taskReminderInterval: parseNonNegativeInteger(productEnv(env, "TASK_REMINDER_INTERVAL") ?? numberConfigValue(files.config.taskReminderInterval), DEFAULT_TASK_REMINDER_INTERVAL, "FORGERELAY_TASK_REMINDER_INTERVAL"),
+        activityPanelExpanded: config.activityPanelExpanded === true,
+        stateDir: resolve(expandHomePath(config.stateDir ?? defaultStateDir())),
+        worktreeRoot: resolve(expandHomePath(config.worktreeRoot ?? defaultWorktreeRoot())),
+        artifactsEnabled: config.artifactsEnabled === true,
+        artifactMaxFileBytes: config.artifactMaxFileBytes ?? DEFAULT_ARTIFACT_MAX_FILE_BYTES,
+        mediaMaxBytes: config.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES,
+        taskReminderInterval: config.taskReminderInterval ?? DEFAULT_TASK_REMINDER_INTERVAL,
         skillsEnabled: productEnv(env, "SKILLS") === undefined ? true : parseBoolean(productEnv(env, "SKILLS")),
         skillPaths: parsePathList(productEnv(env, "SKILL_PATHS")),
         configSkillsDir: forgerelaySkillsDir(env),
-        configAgentsDir: forgerelayAgentsDir(env),
-        subagents: productEnv(env, "SUBAGENTS") === undefined
-            ? files.config.subagents === true
-            : parseBoolean(productEnv(env, "SUBAGENTS")),
-        languageServers: files.config.languageServers ?? {},
-        allowAgentLanguageServerInstall: files.config.allowAgentLanguageServerInstall === true,
-        mcpServers: parseExternalMcpServers(files.config.mcpServers),
-        agentDir: resolve(expandHomePath(productEnv(env, "AGENT_DIR") ?? files.config.agentDir ?? defaultAgentDir())),
-        systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
-        hooks: mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles),
+        subagents: config.subagents === true,
+        allowAgentLanguageServerInstall: config.allowAgentLanguageServerInstall === true,
+        agentDir: resolve(expandHomePath(config.agentDir ?? defaultAgentDir())),
+        systemInstructionsPath: parseSystemInstructionsPath(config.systemInstructionsPath),
         logging: parseLoggingConfig(env, proxyTrust !== false),
         commandShellRuntime,
-        shellInstructionsEnabled: files.config.shellInstructions !== false,
+        shellInstructionsEnabled: config.shellInstructions !== false,
         shellInstructionPath: shellInstructionPath(files.dir, commandShellRuntime.family),
     };
+    configRuntime.captureApplied(generalConfigDefinition, restartRequiredGeneralValues(config, runtimeEnvironment));
+    return serverConfig;
+}
+export function liveGeneralConfigState(config) {
+    const inputs = config.configRuntime.resolutionInputsFor(generalConfigDefinition.domain);
+    const configPath = join(config.configDir, "config.json");
+    const refreshed = refreshGeneralUserConfigSource(config.configRuntime, configPath, inputs.environment);
+    const resolution = resolveGeneralConfig({
+        env: inputs.environment,
+        ...(inputs.cli ? { cli: inputs.cli } : {}),
+        ...(refreshed.value !== undefined
+            ? { user: refreshed.value, userSourcePath: configPath }
+            : {}),
+    });
+    const configured = resolution.values;
+    return {
+        applied: config.configRuntime.snapshotApplied(generalConfigDefinition, restartRequiredGeneralValues(configured, inputs.environment)),
+        ...(refreshed.status.state === "invalid" && refreshed.issue
+            ? {
+                source: {
+                    state: "invalid",
+                    usingLastKnownGood: refreshed.status.usingLastKnownGood,
+                    message: refreshed.issue.message,
+                },
+            }
+            : {}),
+    };
+}
+function refreshGeneralUserConfigSource(runtime, configPath, environment) {
+    return runtime.sources.refreshFile({
+        key: `general:user:${configPath}`,
+        path: configPath,
+        parse: (raw) => JSON.parse(raw),
+        parseIssue: {
+            code: "invalid_source",
+            message: "General configuration is not valid JSON.",
+        },
+        readIssue: {
+            code: "invalid_source",
+            message: "General configuration could not be read.",
+        },
+        validate: (value) => {
+            const validation = resolveGeneralConfig({
+                env: environment,
+                user: value,
+                userSourcePath: configPath,
+            });
+            const error = validation.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+            return error
+                ? { code: error.code === "missing_environment" ? "missing_environment" : "invalid_source", message: error.message }
+                : undefined;
+        },
+    });
+}
+function generalConfigRuntimeEnvironment(env) {
+    const names = new Set(["FORGERELAY_TRUST_PROXY"]);
+    for (const field of Object.values(generalConfigDefinition.fields)) {
+        const configured = field.runtimeOverride?.env;
+        if (!configured)
+            continue;
+        for (const name of Array.isArray(configured) ? configured : [configured])
+            names.add(name);
+    }
+    return Object.fromEntries([...names].flatMap((name) => env[name] === undefined ? [] : [[name, env[name]]]));
 }
-function numberConfigValue(value) {
-    return value === undefined ? undefined : String(value);
+function restartRequiredGeneralValues(configured, env) {
+    const host = configured.host ?? "127.0.0.1";
+    const port = configured.port ?? 7676;
+    const publicDeployment = resolvePublicDeployment(configured.publicBaseUrl, host, port);
+    const proxyTrust = resolveProxyTrust(env, configured, host, publicDeployment.canonicalBaseUrl);
+    const derivedAllowedHosts = [
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        host,
+        ...publicDeployment.baseUrls.map((baseUrl) => new URL(baseUrl).hostname),
+        ...(configured.allowedHosts ?? []),
+    ];
+    return {
+        host,
+        port,
+        allowedRoots: parseAllowedRoots(configured.allowedRoots),
+        publicBaseUrl: publicDeployment.baseUrls,
+        allowedHosts: parseAllowedHosts(configured.allowedHosts, derivedAllowedHosts),
+        trustedProxies: proxyTrust === false ? [] : proxyTrust,
+        stateDir: resolve(expandHomePath(configured.stateDir ?? defaultStateDir())),
+        worktreeRoot: resolve(expandHomePath(configured.worktreeRoot ?? defaultWorktreeRoot())),
+        agentDir: resolve(expandHomePath(configured.agentDir ?? defaultAgentDir())),
+        commandShell: configured.commandShell,
+    };
 }
 function parsePublicBaseUrl(value) {
     const parsed = new URL(value);

package/dist/runtime/config/definition/catalog.js

@@ -0,0 +1,12 @@
+import { externalMcpConfigDefinition } from "./external-mcp.js";
+import { generalConfigDefinition } from "./general-config.js";
+import { languageServersConfigDefinition } from "./language-servers.js";
+import { hooksConfigDefinition } from "../../../mcp/hooks/config.js";
+import { subagentProfilesConfigDefinition } from "../../../subagents/profiles.js";
+export const CONFIG_DEFINITION_CATALOG = [
+    generalConfigDefinition,
+    externalMcpConfigDefinition,
+    languageServersConfigDefinition,
+    hooksConfigDefinition,
+    subagentProfilesConfigDefinition,
+];

package/dist/runtime/config/definition/definition.js

@@ -0,0 +1,115 @@
+import * as z from "zod/v4";
+import { CONFIG_FILE_SCOPES, } from "./types.js";
+const DOMAIN_PATTERN = /^[a-z][a-z0-9-]*$/;
+const FILE_SCOPE_SET = new Set(CONFIG_FILE_SCOPES);
+export function defineConfigDomain(definition) {
+    if (!DOMAIN_PATTERN.test(definition.domain)) {
+        throw new Error(`Invalid config domain name: ${definition.domain}`);
+    }
+    if (!definition.title.trim()) {
+        throw new Error(`Config domain ${definition.domain} requires a title.`);
+    }
+    if (!definition.description.trim()) {
+        throw new Error(`Config domain ${definition.domain} requires a description.`);
+    }
+    for (const [name, field] of Object.entries(definition.fields)) {
+        validateFieldDefinition(definition.domain, name, field);
+    }
+    validateFileShape(definition);
+    return definition;
+}
+export function configSourceSchema(definition, scope) {
+    if (!FILE_SCOPE_SET.has(scope))
+        throw new Error(`Scope ${scope} is not a file-backed config scope.`);
+    const shape = {
+        $schema: z.string().optional().describe("Editor-only JSON Schema URL. Ignored by ForgeRelay resolution."),
+    };
+    for (const [name, field] of Object.entries(definition.fields)) {
+        if (!field.legalScopes.includes(scope))
+            continue;
+        const schema = field.required ? field.schema : field.schema.optional();
+        shape[name] = schema.describe(field.description);
+    }
+    return z.object(shape).strict();
+}
+export function normalizeConfigSourceShape(definition, scope, value, entryKey) {
+    const fileShape = definition.fileShape;
+    if (!fileShape || !FILE_SCOPE_SET.has(scope))
+        return value;
+    if (fileShape.kind === "keyed-root") {
+        if (!isRecord(value))
+            return value;
+        const { $schema, ...entries } = value;
+        return {
+            ...($schema === undefined ? {} : { $schema }),
+            [fileShape.field]: entries,
+        };
+    }
+    if (fileShape.kind === "keyed-entry") {
+        const key = entryKey?.trim();
+        if (!key)
+            throw new Error(`Config domain ${definition.domain} keyed-entry source requires an entry key.`);
+        const parsed = fileShape.fileSchema.parse(value);
+        if (!isRecord(parsed)) {
+            throw new Error(`Config domain ${definition.domain} keyed-entry source must be an object.`);
+        }
+        const { $schema, ...entry } = parsed;
+        const normalized = fileShape.normalizeEntry ? fileShape.normalizeEntry(entry) : entry;
+        return {
+            ...($schema === undefined ? {} : { $schema }),
+            [fileShape.field]: { [key]: normalized },
+        };
+    }
+    return value;
+}
+export function parseConfigSource(definition, scope, value, entryKey) {
+    return configSourceSchema(definition, scope).parse(normalizeConfigSourceShape(definition, scope, value, entryKey));
+}
+export function resolveExecutionEffect(field, value, logicalPath) {
+    return typeof field.executionEffect === "function"
+        ? field.executionEffect(value, logicalPath)
+        : field.executionEffect;
+}
+function validateFileShape(definition) {
+    const fileShape = definition.fileShape;
+    if (!fileShape || fileShape.kind === "object")
+        return;
+    const rootField = definition.fields[fileShape.field];
+    if (!rootField) {
+        throw new Error(`Config domain ${definition.domain} keyed file field ${fileShape.field} is not defined.`);
+    }
+    if (rootField.merge !== "keyed") {
+        throw new Error(`Config domain ${definition.domain} keyed file field ${fileShape.field} must use keyed merge.`);
+    }
+    const otherFileFields = Object.entries(definition.fields).filter(([name, field]) => name !== fileShape.field &&
+        field.legalScopes.some((scope) => FILE_SCOPE_SET.has(scope)));
+    if (otherFileFields.length > 0) {
+        throw new Error(`Config domain ${definition.domain} keyed file shape cannot expose additional file-backed fields.`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateFieldDefinition(domain, name, field) {
+    if (name === "$schema") {
+        throw new Error(`Config domain ${domain} cannot define reserved field $schema.`);
+    }
+    if (!name.trim())
+        throw new Error(`Config domain ${domain} contains an empty field name.`);
+    if (!field.description.trim())
+        throw new Error(`Config field ${domain}.${name} requires a description.`);
+    if (field.legalScopes.length === 0)
+        throw new Error(`Config field ${domain}.${name} requires at least one legal scope.`);
+    if (new Set(field.legalScopes).size !== field.legalScopes.length) {
+        throw new Error(`Config field ${domain}.${name} contains duplicate legal scopes.`);
+    }
+    if (field.builtIn.kind !== "none" && !field.legalScopes.includes("built-in")) {
+        throw new Error(`Config field ${domain}.${name} declares a built-in default without built-in scope.`);
+    }
+    if (field.runtimeOverride && !field.legalScopes.includes("runtime")) {
+        throw new Error(`Config field ${domain}.${name} declares a runtime override without runtime scope.`);
+    }
+    if (field.interpolateValue && field.interpolation !== "env") {
+        throw new Error(`Config field ${domain}.${name} declares a custom interpolator without env interpolation.`);
+    }
+}

package/dist/runtime/config/definition/external-mcp.js

@@ -0,0 +1,58 @@
+import { externalMcpStandaloneServersSchema, } from "../external-mcp-config.js";
+import { defineConfigDomain } from "./definition.js";
+const MCP_SCOPES = ["project-local", "project", "user"];
+const ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+export const externalMcpConfigDefinition = defineConfigDomain({
+    domain: "mcp",
+    title: "ForgeRelay External MCP configuration",
+    description: "Canonical External MCP server configuration. OAuth credentials remain in the machine-private mcp-auth.json store.",
+    fields: {
+        servers: {
+            schema: externalMcpStandaloneServersSchema,
+            description: "External MCP servers keyed by stable server name.",
+            required: true,
+            legalScopes: MCP_SCOPES,
+            merge: "keyed",
+            reload: "hot",
+            sensitivity: "sensitive",
+            interpolation: "env",
+            interpolateValue: interpolateExternalMcpSecrets,
+            builtIn: { kind: "none" },
+            executionEffect: (value) => isRecord(value) && value.transport === "stdio" ? "process" : "none",
+        },
+    },
+});
+function interpolateExternalMcpSecrets(value, environment) {
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([name, entry]) => {
+        if (!isRecord(entry))
+            return [name, entry];
+        const next = { ...entry };
+        if (isRecord(entry.env))
+            next.env = interpolateStringRecord(entry.env, environment);
+        if (isRecord(entry.headers))
+            next.headers = interpolateStringRecord(entry.headers, environment);
+        return [name, next];
+    }));
+}
+function interpolateStringRecord(value, environment) {
+    return Object.fromEntries(Object.entries(value).map(([name, entry]) => [
+        name,
+        typeof entry === "string" ? interpolateString(entry, environment) : entry,
+    ]));
+}
+function interpolateString(value, environment) {
+    return value.replace(ENV_REFERENCE, (_match, name) => {
+        const resolved = environment[name];
+        if (resolved !== undefined)
+            return resolved;
+        const error = new Error(`Required environment variable ${name} is not available.`);
+        error.code = "missing_environment";
+        error.variable = name;
+        throw error;
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}