@akira-tl/forgerelay 1.2.5 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-09-18
+
+### Added
+
+- 新的 domain-first CLI 将运行职责收敛到 `serve`、`init`、`config`、`connect` 与 `system`：`config` 统一 General / Agent Context / External MCP / Hooks / Language Servers / Subagent Profiles 的读取、修改与 provenance 操作，`connect relay` / `connect mcp` 负责运行时连接关系，`system` 负责诊断与维护。
+- `serve` 支持仅当前进程生效的 host、port、allowed root 与 public URL override，不会把调试或多实例参数写回持久配置。
+- Agent context source 现在是 Config System v2 的正式配置：`systemInstructionsPath`、`instructionNames` 与 `skillPaths` 支持 runtime / Project Local / Project / User / built-in precedence、source inspection 和 live refresh。
+
+### Changed
+
+- 裸 `forgerelay` 现在只显示帮助，不再隐式启动服务器；脚本和服务启动应显式使用 `forgerelay serve`。旧 `start`、`hooks`、`auth`、`mcp`、`maintenance` 与 `agents` 路由继续作为不出现在公共 help 中的兼容入口。
+- Agent context built-in defaults 收敛为 `~/.agents/AGENTS.md`、Project instruction basename `AGENTS.md`，以及 `~/.agents/skills` / `./.agents/skills`；ForgeRelay 不再隐式维护 `~/.forgerelay/skills` 或 Project `.forgerelay/skills` 作为 Agent Skill 默认来源。
+- ForgeRelay-owned legacy Config source 继续兼容读取，但 1.3 的 deprecation diagnostic 现在明确显示计划在 `1.4.0` 移除，并继续提供 canonical replacement 路径。
+
+### Fixed
+
+- `forgerelay serve --help` 现在返回专用 serve usage/options，而不是把 `--help` 当成未知启动参数；`system status` 在尚未运行 `init`、没有 Owner credential 的全新环境里也保持只读并报告 `Instance: not initialized` / `Runtime: not running`。
+- `config` domain adapters 现在统一使用 stable resource names、原子 schema-valid mutation 与一致的 Project / global scope 语义；Subagent Profile 名称与各 domain `get` / `set` / `unset` / `remove` contract 保持一致。
+- 带 public base path 的交互式 debug server 现在打印真实 mounted health URL，例如 `/forgerelay/debug/healthz`，而不是错误的 root `/healthz`。
+
 ## [1.2.5] - 2026-09-16
 
 ### Changed

package/README.md

@@ -110,7 +110,7 @@ ForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔
 - Linux / macOS 可以用 Bash、zsh、POSIX sh；Windows 原生支持 PowerShell 7、Windows PowerShell 5.1 和 `cmd.exe`。
 - 同一个 checkout 会保留自己的 Workspace 身份。换一次对话，不需要重新创建工作区。
 - `code.intelligence` 可以查 definition、hover、references、symbols 和 diagnostics。
-- 项目里的 `AGENTS.md`、`CLAUDE.md` 和 Agent Skills 按需加载，不会每次都把整套说明重新塞进上下文。Skill 来自项目级 `.agents/skills`、项目/系统 ForgeRelay Skills 和显式附加路径；不会自动扫描全局 `~/.agents/skills`。
+- Agent 上下文来源走 Config v2：默认 system instructions 是 `~/.agents/AGENTS.md`，项目指令默认只匹配 `AGENTS.md`，Skills 默认按顺序扫描 `~/.agents/skills` 与项目 `./.agents/skills`。项目/User/Project Local/runtime 都可以用 replace semantics 选择其他通用 Agent 目录；ForgeRelay 不再隐式维护 `.forgerelay/skills` 来源。
 - 需要并行开发时可以创建真实 Git worktree；起始 commit 与最终 `targetBranch` 独立，集成仍只接受安全的 fast-forward，不自动制造 merge conflict。
 - 支持 MCP Apps 的 Host 会显示 Workspace Summary / Activity Panel；Workspace 身份色在 Panel 与 pretty log 中保持一致，长路径会在详情区正常换行。
 - Workspace Relay 可以把执行放到另一台 ForgeRelay；Composite Workspace 可以同时协调几个独立环境。
@@ -234,7 +234,7 @@ Long commands do not require tight polling either. Once the current wait window
 - Linux/macOS can use Bash, zsh, or POSIX sh. Windows has native PowerShell 7, Windows PowerShell 5.1, and `cmd.exe` support.
 - Reopening the same checkout reuses the same Workspace identity instead of creating another one for every conversation.
 - `code.intelligence` provides definition, hover, references, symbols, and diagnostics.
-- `AGENTS.md`, `CLAUDE.md`, and Agent Skills are loaded as needed instead of being resent in full on every open. Skills come from project `.agents/skills`, project/system ForgeRelay Skill directories, and explicit extra paths; global `~/.agents/skills` is not scanned automatically.
+- Agent context sources use Config v2: the default system instruction is `~/.agents/AGENTS.md`, project instructions match only `AGENTS.md` by default, and Skills scan `~/.agents/skills` then project `./.agents/skills`. Project/User/Project Local/runtime config can replace those generic sources; ForgeRelay no longer implicitly owns `.forgerelay/skills` sources.
 - Managed worktrees provide real Git isolation when you ask for parallel work. Starting commit and local `targetBranch` are tracked independently, while finalization remains fast-forward-only.
 - MCP Apps-capable hosts can render the Workspace Summary / Activity Panel. Workspace identity colors stay consistent between the panel and pretty logs, and long paths wrap in detail rows instead of hiding their tail.
 - Workspace Relay runs work on another ForgeRelay instance; Composite Workspaces coordinate several independent environments from one Host.

package/dist/cli/config/domains/context-cli.js

@@ -0,0 +1,86 @@
+import { assertConfigResolutionValid } from "../../../runtime/config/resolution/resolver.js";
+import { resolveGeneralConfigForScope, runGeneralConfigSet, runGeneralConfigUnset, } from "../general.js";
+import { runConfigInspection } from "../inspect.js";
+import { parseConfigScopeArgs } from "../scope.js";
+const CONTEXT_FIELDS = [
+    "systemInstructionsPath",
+    "instructionNames",
+    "skillPaths",
+];
+const CONTEXT_LOGICAL_PATHS = new Set(CONTEXT_FIELDS.map((field) => `config.${field}`));
+export async function runConfigContextCommand(args) {
+    const [command, ...rest] = args;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        console.log(renderConfigContextHelp());
+        return;
+    }
+    if (command === "get") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length > 0)
+            throw new Error(`Unknown config context get option: ${parsed.rest[0]}`);
+        const resolution = await resolveGeneralConfigForScope(parsed.scope);
+        assertConfigResolutionValid(resolution);
+        const output = Object.fromEntries(CONTEXT_FIELDS.map((field) => {
+            const entry = resolution.entries[field];
+            if (!entry)
+                throw new Error(`Missing General Config context field: config.${field}.`);
+            return [field, entry.effective.effectiveValue];
+        }));
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    if (command === "set") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length < 2) {
+            throw new Error("Usage: forgerelay config context set <field> <value> [--project <path>|--global]");
+        }
+        const field = normalizeContextField(parsed.rest[0]);
+        await runGeneralConfigSet([field, ...parsed.rest.slice(1), ...scopeArgs(parsed.scope)]);
+        return;
+    }
+    if (command === "unset") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1) {
+            throw new Error("Usage: forgerelay config context unset <field> [--project <path>|--global]");
+        }
+        const field = normalizeContextField(parsed.rest[0]);
+        await runGeneralConfigUnset([field, ...scopeArgs(parsed.scope)]);
+        return;
+    }
+    if (command === "check" || command === "sources") {
+        process.exitCode = await runConfigInspection([command, ...rest], "config", CONTEXT_LOGICAL_PATHS);
+        return;
+    }
+    if (command === "explain") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length < 1) {
+            throw new Error("Usage: forgerelay config context explain <field> [--project <path>|--global] [--json]");
+        }
+        const field = normalizeContextField(parsed.rest[0]);
+        process.exitCode = await runConfigInspection(["explain", `config.${field}`, ...parsed.rest.slice(1), ...scopeArgs(parsed.scope)], "config", CONTEXT_LOGICAL_PATHS);
+        return;
+    }
+    throw new Error(`Unknown config context command: ${command}`);
+}
+function normalizeContextField(value) {
+    const field = value.startsWith("config.") ? value.slice("config.".length) : value;
+    if (CONTEXT_FIELDS.includes(field))
+        return field;
+    throw new Error(`Unknown config context field: ${value}. Expected ${CONTEXT_FIELDS.join(", ")}.`);
+}
+function scopeArgs(scope) {
+    return scope.mode === "global" ? ["--global"] : ["--project", scope.projectRoot];
+}
+function renderConfigContextHelp() {
+    return [
+        "ForgeRelay config context",
+        "",
+        "Usage:",
+        "  forgerelay config context get [--project <path>|--global]",
+        "  forgerelay config context set <systemInstructionsPath|instructionNames|skillPaths> <value> [--project <path>|--global]",
+        "  forgerelay config context unset <systemInstructionsPath|instructionNames|skillPaths> [--project <path>|--global]",
+        "  forgerelay config context check [--project <path>|--global] [--json]",
+        "  forgerelay config context sources [--project <path>|--global] [--json]",
+        "  forgerelay config context explain <systemInstructionsPath|instructionNames|skillPaths> [--project <path>|--global] [--json]",
+    ].join("\n");
+}

package/dist/cli/config/domains/domain-cli.js

@@ -0,0 +1,468 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseConfigSource } from "../../../runtime/config/definition/definition.js";
+import { externalMcpConfigDefinition } from "../../../runtime/config/definition/external-mcp.js";
+import { hooksConfigDefinition } from "../../../mcp/hooks/config.js";
+import { languageServersConfigDefinition } from "../../../runtime/config/definition/language-servers.js";
+import { ExternalMcpConfigRegistry } from "../../../runtime/config/external-mcp-registry.js";
+import { resolveHooksConfig } from "../../../runtime/config/resolution/hooks.js";
+import { resolveLanguageServersConfig } from "../../../runtime/config/resolution/language-servers.js";
+import { assertConfigResolutionValid } from "../../../runtime/config/resolution/resolver.js";
+import { ConfigSourceRuntime } from "../../../runtime/config/runtime/source-refresh.js";
+import { forgerelayConfigDir, writeConfigJsonFile, writeConfigTextFile } from "../../../runtime/config/user-config.js";
+import { ProjectContextResolver } from "../../../workspaces/state/project-context.js";
+import { canonicalSubagentProfileDocument, canonicalSubagentProfileValueFromDocument, resolveSubagentProfilesConfigSources, } from "../../../subagents/profiles.js";
+import { runConfigInspection } from "../inspect.js";
+import { parseConfigScopeArgs } from "../scope.js";
+import { runConfigContextCommand } from "./context-cli.js";
+const JSON_DOMAIN_ADAPTERS = {
+    mcp: {
+        cliName: "mcp",
+        resolutionDomain: "mcp",
+        definition: externalMcpConfigDefinition,
+        fileName: "mcp.json",
+        rootField: "servers",
+        diskShape: "object",
+        resolve: resolveMcpConfiguration,
+    },
+    lsp: {
+        cliName: "lsp",
+        resolutionDomain: "language-servers",
+        definition: languageServersConfigDefinition,
+        fileName: "language-servers.json",
+        rootField: "servers",
+        diskShape: "keyed-root",
+        resolve: resolveLanguageServerConfiguration,
+    },
+};
+export async function runConfigDomainCommand(domain, args) {
+    if (domain === "context") {
+        await runConfigContextCommand(args);
+        return true;
+    }
+    const adapter = JSON_DOMAIN_ADAPTERS[domain];
+    if (adapter) {
+        await runJsonDomainCommand(adapter, args);
+        return true;
+    }
+    if (domain === "hooks") {
+        if (args[0] === "list" || args[0] === "help" || args[0] === "--help" || args[0] === "-h" || args[0] === undefined) {
+            return false;
+        }
+        await runHookDomainCommand(args);
+        return true;
+    }
+    if (domain === "subagents") {
+        await runSubagentDomainCommand(args);
+        return true;
+    }
+    return false;
+}
+async function runHookDomainCommand(args) {
+    const [command, ...rest] = args;
+    if (command === "check" || command === "sources" || command === "explain") {
+        process.exitCode = await runDomainInspection("hooks", "hooks", command, rest);
+        return;
+    }
+    if (command === "get") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1)
+            throw new Error("Usage: forgerelay config hooks get hooks.<name> [scope]");
+        const resolution = await resolveHookConfiguration(parsed.scope);
+        printConfiguredEntry(resolution, normalizeDomainLogicalPath("hooks", "hooks", parsed.rest[0]));
+        return;
+    }
+    if (command === "set") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length < 2)
+            throw new Error("Usage: forgerelay config hooks set hooks.<name>[.<field>] <value> [scope]");
+        const [logicalPath, ...valueParts] = parsed.rest;
+        const segments = domainLogicalSegments("hooks", "hooks", logicalPath);
+        const name = safeResourceName(segments[1] ?? "");
+        const target = await domainWriteTarget(parsed.scope, join("hooks", `${name}.json`));
+        const rawValue = valueParts.join(" ").trim();
+        if (!rawValue)
+            throw new Error(`Missing value for ${logicalPath}.`);
+        const candidate = segments.length === 2
+            ? coerceConfigValue(rawValue)
+            : mutateExistingJson(target.path, segments.slice(2), coerceConfigValue(rawValue), "set");
+        if (!isRecord(candidate))
+            throw new Error(`hooks.${name} must be a JSON object.`);
+        writeHookTarget(target, name, candidate);
+        return;
+    }
+    if (command === "unset") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1)
+            throw new Error("Usage: forgerelay config hooks unset hooks.<name>.<field> [scope]");
+        const segments = domainLogicalSegments("hooks", "hooks", parsed.rest[0]);
+        if (segments.length < 3)
+            throw new Error("Use `config hooks remove <name>` to delete a complete Hook.");
+        const name = safeResourceName(segments[1]);
+        const target = await domainWriteTarget(parsed.scope, join("hooks", `${name}.json`));
+        const candidate = mutateExistingJson(target.path, segments.slice(2), undefined, "unset");
+        writeHookTarget(target, name, candidate);
+        return;
+    }
+    if (command === "remove") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1)
+            throw new Error("Usage: forgerelay config hooks remove <name> [scope]");
+        const name = safeResourceName(parsed.rest[0]);
+        const target = await domainWriteTarget(parsed.scope, join("hooks", `${name}.json`));
+        rmSync(target.path, { force: true });
+        console.log(`Removed ${target.path}`);
+        return;
+    }
+    throw new Error(`Unknown config hooks command: ${command ?? ""}`);
+}
+async function runSubagentDomainCommand(args) {
+    const [command, ...rest] = args;
+    if (command === "check" || command === "sources" || command === "explain") {
+        process.exitCode = await runDomainInspection("subagents", "profiles", command, rest);
+        return;
+    }
+    if (command === "get") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1)
+            throw new Error("Usage: forgerelay config subagents get profiles.<name> [scope]");
+        const resolution = await resolveSubagentConfiguration(parsed.scope);
+        printConfiguredEntry(resolution, normalizeDomainLogicalPath("subagents", "profiles", parsed.rest[0]));
+        return;
+    }
+    if (command === "set") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length < 2)
+            throw new Error("Usage: forgerelay config subagents set profiles.<name>[.<field>] <value> [scope]");
+        const [logicalPath, ...valueParts] = parsed.rest;
+        const segments = domainLogicalSegments("subagents", "profiles", logicalPath);
+        const name = safeResourceName(segments[1] ?? "");
+        const target = await subagentWriteTarget(parsed.scope, name);
+        const rawValue = valueParts.join(" ").trim();
+        if (!rawValue)
+            throw new Error(`Missing value for ${logicalPath}.`);
+        const candidate = segments.length === 2
+            ? coerceConfigValue(rawValue)
+            : mutateExistingSubagent(target.path, segments.slice(2), coerceConfigValue(rawValue), "set");
+        writeSubagentTarget(target, name, candidate);
+        return;
+    }
+    if (command === "unset") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1)
+            throw new Error("Usage: forgerelay config subagents unset profiles.<name>.<field> [scope]");
+        const segments = domainLogicalSegments("subagents", "profiles", parsed.rest[0]);
+        if (segments.length < 3)
+            throw new Error("Use `config subagents remove <name>` to delete a complete profile.");
+        const name = safeResourceName(segments[1]);
+        const target = await subagentWriteTarget(parsed.scope, name);
+        const candidate = mutateExistingSubagent(target.path, segments.slice(2), undefined, "unset");
+        writeSubagentTarget(target, name, candidate);
+        return;
+    }
+    if (command === "remove") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1)
+            throw new Error("Usage: forgerelay config subagents remove <name> [scope]");
+        const name = safeResourceName(parsed.rest[0]);
+        const target = await subagentWriteTarget(parsed.scope, name);
+        rmSync(target.path, { force: true });
+        console.log(`Removed ${target.path}`);
+        return;
+    }
+    throw new Error(`Unknown config subagents command: ${command ?? ""}`);
+}
+async function runJsonDomainCommand(adapter, args) {
+    const [command, ...rest] = args;
+    if (command === "check" || command === "sources" || command === "explain") {
+        process.exitCode = await runDomainInspection(adapter.resolutionDomain, adapter.rootField, command, rest);
+        return;
+    }
+    if (command === "get") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1) {
+            throw new Error(`Usage: forgerelay config ${adapter.cliName} get <logical-path> [--project <path>|--global]`);
+        }
+        const logicalPath = normalizeDomainLogicalPath(adapter.resolutionDomain, adapter.rootField, parsed.rest[0]);
+        const resolution = await adapter.resolve(parsed.scope);
+        printConfiguredEntry(resolution, logicalPath);
+        return;
+    }
+    if (command === "set") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length < 2) {
+            throw new Error(`Usage: forgerelay config ${adapter.cliName} set <logical-path> <value> [--project <path>|--global]`);
+        }
+        const [logicalPath, ...valueParts] = parsed.rest;
+        const path = storagePathSegments(adapter, logicalPath);
+        const rawValue = valueParts.join(" ").trim();
+        if (!rawValue)
+            throw new Error(`Missing value for ${logicalPath}.`);
+        const target = await domainWriteTarget(parsed.scope, adapter.fileName);
+        const next = readJsonObject(target.path, domainFallback(adapter));
+        setNestedValue(next, path, coerceConfigValue(rawValue));
+        writeJsonDomainTarget(adapter, target, next);
+        return;
+    }
+    if (command === "unset") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1) {
+            throw new Error(`Usage: forgerelay config ${adapter.cliName} unset <logical-path> [--project <path>|--global]`);
+        }
+        const target = await domainWriteTarget(parsed.scope, adapter.fileName);
+        const next = readJsonObject(target.path, domainFallback(adapter));
+        const path = storagePathSegments(adapter, parsed.rest[0]);
+        if (isCompleteJsonResourcePath(adapter, path)) {
+            throw new Error(`Use \`config ${adapter.cliName} remove <name>\` to delete a complete resource.`);
+        }
+        deleteNestedValue(next, path);
+        writeJsonDomainTarget(adapter, target, next);
+        return;
+    }
+    if (command === "remove") {
+        const parsed = parseConfigScopeArgs(rest);
+        if (parsed.rest.length !== 1) {
+            throw new Error(`Usage: forgerelay config ${adapter.cliName} remove <name> [--project <path>|--global]`);
+        }
+        const target = await domainWriteTarget(parsed.scope, adapter.fileName);
+        const next = readJsonObject(target.path, domainFallback(adapter));
+        const resourcePath = adapter.diskShape === "keyed-root"
+            ? [parsed.rest[0]]
+            : [adapter.rootField, parsed.rest[0]];
+        deleteNestedValue(next, resourcePath);
+        writeJsonDomainTarget(adapter, target, next);
+        return;
+    }
+    throw new Error(`Unknown config ${adapter.cliName} command: ${command ?? ""}`);
+}
+async function runDomainInspection(domain, rootField, command, args) {
+    const inspectionArgs = command === "explain"
+        ? [command, ...normalizeDomainExplainArgs(domain, rootField, args)]
+        : [command, ...args];
+    return runConfigInspection(inspectionArgs, domain);
+}
+function printConfiguredEntry(resolution, logicalPath) {
+    assertConfigResolutionValid(resolution);
+    const entry = Object.values(resolution.entries).find((candidate) => candidate.logicalPath === logicalPath);
+    if (!entry || entry.tombstone)
+        throw new Error(`Unknown configuration logical path: ${logicalPath}.`);
+    console.log(JSON.stringify(entry.effective.effectiveValue, null, 2));
+}
+async function resolveMcpConfiguration(scope) {
+    const configDir = forgerelayConfigDir();
+    const registry = new ExternalMcpConfigRegistry({ configDir, environment: process.env });
+    if (scope.mode === "global")
+        return registry.resolveConfiguration();
+    const project = await new ProjectContextResolver(configDir).inspect(scope.projectRoot);
+    return registry.resolveConfiguration({
+        projectSharedConfigDir: project.sharedConfigDir,
+        ...(project.localConfigDir ? { projectLocalConfigDir: project.localConfigDir } : {}),
+    });
+}
+async function resolveHookConfiguration(scope) {
+    const configDir = forgerelayConfigDir();
+    if (scope.mode === "global")
+        return resolveHooksConfig({ configDir });
+    const project = await new ProjectContextResolver(configDir).inspect(scope.projectRoot);
+    return resolveHooksConfig({
+        configDir,
+        ...(project.localConfigDir
+            ? { project: { sharedConfigDir: project.sharedConfigDir, localConfigDir: project.localConfigDir } }
+            : { projectSharedConfigDir: project.sharedConfigDir }),
+    });
+}
+async function subagentWriteTarget(scope, name) {
+    const resolution = await resolveSubagentConfiguration(scope);
+    const entry = resolution.entries[`profiles.${name}`];
+    const targetScope = scope.mode === "global" ? "user" : "project";
+    const candidate = entry
+        ? [entry.effective, ...entry.shadowed].find((value) => value.source.scope === targetScope &&
+            value.source.id.startsWith(`canonical:${targetScope}:subagent:`) &&
+            value.source.location !== undefined)
+        : undefined;
+    if (candidate?.source.location) {
+        return { scope: targetScope, path: candidate.source.location };
+    }
+    return domainWriteTarget(scope, join("subagents", `${name}.md`));
+}
+async function resolveSubagentConfiguration(scope) {
+    const configDir = forgerelayConfigDir();
+    const sourceRuntime = new ConfigSourceRuntime();
+    if (scope.mode === "global") {
+        return resolveSubagentProfilesConfigSources({ configDir, sourceRuntime });
+    }
+    const project = await new ProjectContextResolver(configDir).inspect(scope.projectRoot);
+    return resolveSubagentProfilesConfigSources({
+        configDir,
+        sourceRuntime,
+        projectSharedConfigDir: project.sharedConfigDir,
+        ...(project.localConfigDir ? { projectLocalConfigDir: project.localConfigDir } : {}),
+    });
+}
+async function resolveLanguageServerConfiguration(scope) {
+    const configDir = forgerelayConfigDir();
+    if (scope.mode === "global") {
+        return resolveLanguageServersConfig({ configDir, environment: process.env });
+    }
+    const project = await new ProjectContextResolver(configDir).inspect(scope.projectRoot);
+    return resolveLanguageServersConfig({
+        configDir,
+        environment: process.env,
+        ...(project.localConfigDir
+            ? { project: { sharedConfigDir: project.sharedConfigDir, localConfigDir: project.localConfigDir } }
+            : { projectSharedConfigDir: project.sharedConfigDir }),
+    });
+}
+function writeJsonDomainTarget(adapter, target, value) {
+    const validated = parseConfigSource(adapter.definition, target.scope, value);
+    const diskValue = adapter.diskShape === "keyed-root" ? value : validated;
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeConfigJsonFile(target.path, diskValue, 0o600);
+    console.log(`Updated ${target.path}`);
+}
+function writeHookTarget(target, name, value) {
+    parseConfigSource(hooksConfigDefinition, target.scope, value, name);
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeConfigJsonFile(target.path, value, 0o600);
+    console.log(`Updated ${target.path}`);
+}
+function writeSubagentTarget(target, name, value) {
+    const document = canonicalSubagentProfileDocument(name, value);
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeConfigTextFile(target.path, document, 0o600);
+    console.log(`Updated ${target.path}`);
+}
+function mutateExistingJson(path, nestedPath, value, action) {
+    if (!existsSync(path))
+        throw new Error(`Configuration resource does not exist: ${path}`);
+    const next = readJsonObject(path, {});
+    if (action === "set")
+        setNestedValue(next, nestedPath, value);
+    else
+        deleteNestedValue(next, nestedPath);
+    return next;
+}
+function mutateExistingSubagent(path, nestedPath, value, action) {
+    if (!existsSync(path))
+        throw new Error(`Subagent Profile does not exist: ${path}`);
+    const current = canonicalSubagentProfileValueFromDocument(readFileSync(path, "utf8"), path);
+    if (!isRecord(current))
+        throw new Error(`Subagent Profile is not editable: ${path}`);
+    const next = structuredClone(current);
+    if (action === "set")
+        setNestedValue(next, nestedPath, value);
+    else
+        deleteNestedValue(next, nestedPath);
+    return next;
+}
+async function domainWriteTarget(scope, fileName) {
+    const configDir = forgerelayConfigDir();
+    if (scope.mode === "global")
+        return { scope: "user", path: join(configDir, fileName) };
+    const project = await new ProjectContextResolver(configDir).inspect(scope.projectRoot);
+    return { scope: "project", path: join(project.sharedConfigDir, fileName) };
+}
+function domainFallback(adapter) {
+    return adapter.diskShape === "keyed-root" ? {} : { [adapter.rootField]: {} };
+}
+function readJsonObject(path, fallback) {
+    if (!existsSync(path))
+        return structuredClone(fallback);
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(parsed))
+        throw new Error(`Configuration source must be a JSON object: ${path}`);
+    return structuredClone(parsed);
+}
+function safeResourceName(value) {
+    const name = value.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name === "." || name === "..") {
+        throw new Error(`Invalid configuration resource name: ${value}.`);
+    }
+    return name;
+}
+function isCompleteJsonResourcePath(adapter, path) {
+    return adapter.diskShape === "keyed-root"
+        ? path.length === 1
+        : path.length === 2 && path[0] === adapter.rootField;
+}
+function storagePathSegments(adapter, logicalPath) {
+    const segments = domainLogicalSegments(adapter.resolutionDomain, adapter.rootField, logicalPath);
+    if (segments[0] !== adapter.rootField || segments.length < 2) {
+        throw new Error(`${adapter.cliName} logical paths must start with ${adapter.rootField}.<name>.`);
+    }
+    return adapter.diskShape === "keyed-root" ? segments.slice(1) : segments;
+}
+function domainLogicalSegments(domain, rootField, logicalPath) {
+    const normalized = normalizeDomainLogicalPath(domain, rootField, logicalPath);
+    return normalized.slice(`${domain}.`.length).split(".").filter(Boolean);
+}
+function normalizeDomainLogicalPath(domain, rootField, logicalPath) {
+    const normalized = logicalPath.trim();
+    if (!normalized)
+        throw new Error(`Invalid ${domain} logical path: ${logicalPath}.`);
+    const fullyQualifiedRoot = `${domain}.${rootField}`;
+    if (normalized === fullyQualifiedRoot || normalized.startsWith(`${fullyQualifiedRoot}.`))
+        return normalized;
+    return `${domain}.${normalized}`;
+}
+function normalizeDomainExplainArgs(domain, rootField, args) {
+    const normalized = [];
+    let logicalPathSeen = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--project") {
+            normalized.push(arg);
+            const project = args[index + 1];
+            if (project !== undefined) {
+                normalized.push(project);
+                index += 1;
+            }
+            continue;
+        }
+        if (arg === "--global" || arg === "--json") {
+            normalized.push(arg);
+            continue;
+        }
+        if (!logicalPathSeen) {
+            normalized.push(normalizeDomainLogicalPath(domain, rootField, arg));
+            logicalPathSeen = true;
+            continue;
+        }
+        normalized.push(arg);
+    }
+    return normalized;
+}
+function coerceConfigValue(rawValue) {
+    try {
+        return JSON.parse(rawValue);
+    }
+    catch {
+        return rawValue;
+    }
+}
+function setNestedValue(target, path, value) {
+    let current = target;
+    for (const segment of path.slice(0, -1)) {
+        const existing = current[segment];
+        if (existing !== undefined && !isRecord(existing)) {
+            throw new Error(`Cannot set ${path.join(".")}: ${segment} is not an object.`);
+        }
+        const next = existing ?? {};
+        current[segment] = next;
+        current = next;
+    }
+    current[path[path.length - 1]] = value;
+}
+function deleteNestedValue(target, path) {
+    let current = target;
+    for (const segment of path.slice(0, -1)) {
+        const existing = current[segment];
+        if (!isRecord(existing))
+            return;
+        current = existing;
+    }
+    delete current[path[path.length - 1]];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}