@akira-tl/forgerelay 0.1.0

package/dist/workspaces.js

@@ -0,0 +1,528 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
+import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
+import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
+import { loadLocalAgentProfiles, } from "./local-agent-profiles.js";
+export class WorkspaceRegistry {
+    config;
+    store;
+    workspaces = new Map();
+    pendingOpens = new Map();
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+    }
+    async openWorkspace(input, openOptions = {}) {
+        const workspaceInput = typeof input === "string" ? { path: input } : input;
+        const mode = workspaceInput.mode ?? "checkout";
+        if (mode === "worktree") {
+            return this.openReusableWorktree(workspaceInput, openOptions.conversationScopeId);
+        }
+        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId);
+    }
+    async listKnownWorktrees(workspace) {
+        const sourceRoot = workspace.mode === "worktree" ? workspace.sourceRoot : workspace.root;
+        if (!sourceRoot)
+            return [];
+        const sourceKey = await canonicalPath(sourceRoot);
+        const results = [];
+        for (const session of this.activeSessions("worktree")) {
+            if (!session.sourceRoot)
+                continue;
+            if (await canonicalPath(session.sourceRoot) !== sourceKey)
+                continue;
+            const root = await this.validSessionRoot(session);
+            if (!root)
+                continue;
+            results.push({
+                workspaceId: session.id,
+                path: root,
+                baseRef: session.baseRef ?? "HEAD",
+                baseSha: session.baseSha ?? "",
+                branch: session.branch,
+                targetBranch: session.targetBranch,
+                managed: session.managed,
+                current: session.id === workspace.id,
+            });
+        }
+        return results;
+    }
+    async closeWorktree(workspaceId, commitMessage) {
+        const workspace = this.getWorkspace(workspaceId);
+        if (workspace.mode !== "worktree" || !workspace.worktree?.managed || !workspace.sourceRoot) {
+            throw new Error(`Workspace ${workspaceId} is not a managed worktree workspace.`);
+        }
+        if (workspace.worktree.detached ||
+            !workspace.worktree.branch ||
+            !workspace.worktree.targetBranch) {
+            throw new Error(`Workspace ${workspaceId} is a legacy detached worktree and cannot use the managed close lifecycle. Create a branch for it explicitly or open a new managed worktree.`);
+        }
+        const managedWorktree = {
+            sourceRoot: workspace.sourceRoot,
+            path: workspace.worktree.path,
+            baseRef: workspace.worktree.baseRef,
+            baseSha: workspace.worktree.baseSha,
+            branch: workspace.worktree.branch,
+            targetBranch: workspace.worktree.targetBranch,
+            dirtySource: workspace.worktree.dirtySource,
+            detached: false,
+            managed: true,
+        };
+        const result = await closeManagedWorktree({
+            worktree: managedWorktree,
+            commitMessage,
+            config: this.config,
+        });
+        this.store?.setSessionStatus(workspace.id, "closed");
+        this.workspaces.delete(workspace.id);
+        return result;
+    }
+    async openReusableCheckout(path, conversationScopeId) {
+        const allowedPath = assertAllowedPath(path, this.config.allowedRoots);
+        const projectKey = await canonicalPath(allowedPath);
+        const targetKey = JSON.stringify(["checkout", projectKey, null]);
+        const context = await this.openOnce(targetKey, async () => {
+            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
+            return reusableWorkspace
+                ? this.reusedWorkspaceContext(reusableWorkspace)
+                : this.openCheckoutWorkspace(path);
+        });
+        return this.withConversationContext(context, conversationScopeId, targetKey);
+    }
+    async openReusableWorktree(input, conversationScopeId) {
+        const managedPath = this.tryManagedWorktreePath(input.path);
+        if (managedPath) {
+            const worktreeKey = await canonicalPath(managedPath);
+            const targetKey = JSON.stringify(["worktree-path", worktreeKey]);
+            const context = await this.openOnce(targetKey, async () => {
+                const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
+                if (!reusableWorkspace) {
+                    throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
+                }
+                return this.reusedWorkspaceContext(reusableWorkspace);
+            });
+            return this.withConversationContext(context, conversationScopeId, targetKey);
+        }
+        const resolvedBase = await resolveManagedWorktreeBase({
+            sourcePath: input.path,
+            baseRef: input.baseRef,
+            config: this.config,
+        });
+        const sourceKey = await canonicalPath(resolvedBase.sourceRoot);
+        const targetKey = JSON.stringify(["worktree", sourceKey, resolvedBase.targetBranch]);
+        if (input.newWorktree) {
+            const context = await this.openWorktreeWorkspace(input.path, input.baseRef);
+            return this.withConversationContext(context, conversationScopeId, targetKey);
+        }
+        const context = await this.openOnce(targetKey, async () => {
+            const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
+            return reusableWorkspace
+                ? this.reusedWorkspaceContext(reusableWorkspace)
+                : this.openWorktreeWorkspace(input.path, input.baseRef);
+        });
+        return this.withConversationContext(context, conversationScopeId, targetKey);
+    }
+    async openOnce(operationKey, open) {
+        const pending = this.pendingOpens.get(operationKey);
+        if (pending) {
+            const context = await pending;
+            return { ...context, workspaceReused: true };
+        }
+        const operation = open();
+        this.pendingOpens.set(operationKey, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.pendingOpens.get(operationKey) === operation) {
+                this.pendingOpens.delete(operationKey);
+            }
+        }
+    }
+    withConversationContext(context, conversationScopeId, targetKey) {
+        if (!conversationScopeId || !this.store) {
+            return { ...context, includeBootstrapContext: true };
+        }
+        const binding = this.store.getConversationBinding(conversationScopeId, targetKey);
+        if (binding?.workspaceSessionId === context.workspace.id) {
+            this.store.touchConversationBinding(conversationScopeId, targetKey);
+            return { ...context, includeBootstrapContext: false };
+        }
+        this.store.setConversationBinding({
+            conversationScopeId,
+            targetKey,
+            workspaceSessionId: context.workspace.id,
+        });
+        return { ...context, includeBootstrapContext: true };
+    }
+    async findReusableWorkspaceByDirectory(directoryKey, mode) {
+        for (const session of this.activeSessions(mode)) {
+            const root = await this.validSessionRoot(session);
+            if (!root)
+                continue;
+            if (await canonicalPath(root) !== directoryKey)
+                continue;
+            return this.getWorkspace(session.id);
+        }
+        return undefined;
+    }
+    async findReusableWorktreeBySource(sourceKey, targetBranch) {
+        for (const session of this.activeSessions("worktree")) {
+            if (!session.sourceRoot || session.targetBranch !== targetBranch)
+                continue;
+            if (await canonicalPath(session.sourceRoot) !== sourceKey)
+                continue;
+            const root = await this.validSessionRoot(session);
+            if (!root)
+                continue;
+            return this.getWorkspace(session.id);
+        }
+        return undefined;
+    }
+    activeSessions(mode) {
+        if (this.store) {
+            return this.store.listSessions({ status: "active", mode });
+        }
+        return [...this.workspaces.values()]
+            .filter((workspace) => workspace.mode === mode)
+            .map((workspace) => ({
+            id: workspace.id,
+            root: workspace.root,
+            status: "active",
+            mode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            baseRef: workspace.worktree?.baseRef,
+            baseSha: workspace.worktree?.baseSha,
+            branch: workspace.worktree?.branch,
+            targetBranch: workspace.worktree?.targetBranch,
+            managed: workspace.worktree?.managed ?? false,
+            createdAt: "",
+            lastUsedAt: "",
+        }));
+    }
+    async validSessionRoot(session) {
+        try {
+            const root = this.assertWorkspaceRootAllowed(session.root, session.mode, session.sourceRoot);
+            const rootStats = await stat(root);
+            return rootStats.isDirectory() ? root : undefined;
+        }
+        catch (error) {
+            if (error instanceof AccessDeniedError ||
+                (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    tryManagedWorktreePath(path) {
+        try {
+            return assertAllowedPath(path, [this.config.worktreeRoot]);
+        }
+        catch (error) {
+            if (error instanceof AccessDeniedError)
+                return undefined;
+            throw error;
+        }
+    }
+    async reusedWorkspaceContext(workspace) {
+        workspace.agentProfiles = await loadLocalAgentProfiles(this.config, workspace.root);
+        const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
+        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        return {
+            workspace,
+            agentsFiles,
+            availableAgentsFiles,
+            workspaceReused: true,
+            includeBootstrapContext: true,
+        };
+    }
+    getWorkspace(workspaceId) {
+        const workspace = this.workspaces.get(workspaceId);
+        if (workspace) {
+            this.store?.touchSession(workspaceId);
+            return workspace;
+        }
+        const session = this.store?.getSession(workspaceId);
+        if (!session || session.status !== "active") {
+            throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
+        }
+        const root = this.assertWorkspaceRootAllowed(session.root, session.mode, session.sourceRoot);
+        const restoredWorkspace = {
+            id: session.id,
+            root,
+            mode: session.mode,
+            sourceRoot: session.sourceRoot,
+            worktree: session.mode === "worktree"
+                ? {
+                    path: root,
+                    baseRef: session.baseRef ?? "HEAD",
+                    baseSha: session.baseSha ?? "",
+                    branch: session.branch,
+                    targetBranch: session.targetBranch,
+                    dirtySource: false,
+                    detached: !session.branch,
+                    managed: session.managed,
+                }
+                : undefined,
+            ...this.loadSkillsForWorkspace(root),
+            agentProfiles: [],
+            activatedSkillDirs: new Set(),
+        };
+        this.store?.touchSession(workspaceId);
+        this.workspaces.set(restoredWorkspace.id, restoredWorkspace);
+        return restoredWorkspace;
+    }
+    resolvePath(workspace, inputPath) {
+        const absolutePath = resolveAllowedPath(inputPath, workspace.root, [workspace.root]);
+        if (!isPathInsideRoot(absolutePath, workspace.root)) {
+            throw new Error(`Path is outside workspace root: ${inputPath}`);
+        }
+        return absolutePath;
+    }
+    resolveReadPath(workspace, inputPath) {
+        try {
+            return {
+                absolutePath: this.resolvePath(workspace, inputPath),
+                readRoots: [workspace.root],
+            };
+        }
+        catch (workspaceError) {
+            const skillRead = resolveSkillReadPath(workspace.skills, workspace.activatedSkillDirs, inputPath);
+            if (!skillRead)
+                throw workspaceError;
+            return {
+                absolutePath: skillRead.absolutePath,
+                readRoots: [workspace.root, skillRead.skill.baseDir],
+                skillRead,
+            };
+        }
+    }
+    markReadPathLoaded(workspace, readPath) {
+        if (readPath.skillRead?.isSkillFile) {
+            markSkillActivated(workspace.activatedSkillDirs, readPath.skillRead.skill);
+        }
+    }
+    resolveWorkingDirectory(workspace, workingDirectory) {
+        const directory = workingDirectory ? this.resolvePath(workspace, workingDirectory) : workspace.root;
+        return assertAllowedPath(directory, [workspace.root]);
+    }
+    async openCheckoutWorkspace(path) {
+        const root = assertAllowedPath(path, this.config.allowedRoots);
+        const rootStats = await ensureCheckoutWorkspaceRoot(root);
+        if (!rootStats.isDirectory()) {
+            throw new Error(`Workspace root must be a directory: ${path}`);
+        }
+        return this.createWorkspaceContext({ root, mode: "checkout" });
+    }
+    async openWorktreeWorkspace(path, baseRef) {
+        const worktree = await createManagedWorktree({
+            sourcePath: path,
+            baseRef,
+            config: this.config,
+        });
+        return this.createWorkspaceContext({
+            root: worktree.path,
+            mode: "worktree",
+            sourceRoot: worktree.sourceRoot,
+            worktree,
+        });
+    }
+    async createWorkspaceContext(input) {
+        const workspace = {
+            id: `ws_${randomBytes(5).toString("hex")}`,
+            root: input.root,
+            mode: input.mode,
+            sourceRoot: input.sourceRoot,
+            worktree: input.worktree,
+            ...this.loadSkillsForWorkspace(input.root),
+            agentProfiles: await loadLocalAgentProfiles(this.config, input.root),
+            activatedSkillDirs: new Set(),
+        };
+        this.store?.createSession({
+            id: workspace.id,
+            root: workspace.root,
+            mode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            baseRef: workspace.worktree?.baseRef,
+            baseSha: workspace.worktree?.baseSha,
+            branch: workspace.worktree?.branch,
+            targetBranch: workspace.worktree?.targetBranch,
+            managed: workspace.worktree?.managed,
+        });
+        this.workspaces.set(workspace.id, workspace);
+        const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
+        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        return {
+            workspace,
+            agentsFiles,
+            availableAgentsFiles,
+            workspaceReused: false,
+            includeBootstrapContext: true,
+        };
+    }
+    loadSkillsForWorkspace(root) {
+        const result = loadWorkspaceSkills(this.config, root);
+        return {
+            skills: result.skills,
+            skillDiagnostics: result.diagnostics,
+        };
+    }
+    assertWorkspaceRootAllowed(root, mode, sourceRoot) {
+        if (mode === "worktree") {
+            if (!sourceRoot) {
+                throw new Error(`Stored worktree workspace is missing sourceRoot: ${root}`);
+            }
+            assertAllowedPath(sourceRoot, this.config.allowedRoots);
+            return assertAllowedPath(root, [this.config.worktreeRoot]);
+        }
+        return assertAllowedPath(root, this.config.allowedRoots);
+    }
+    async loadInitialAgentsFiles(root) {
+        const agentDir = resolve(this.config.agentDir);
+        const resolvedRoot = (await tryRealpath(root)) ?? root;
+        const resolvedAgentDir = (await tryRealpath(agentDir)) ?? agentDir;
+        const loadedFiles = [];
+        for (const file of loadProjectContextFiles({ cwd: root, agentDir })) {
+            const path = resolve(file.path);
+            if (!isInitialAgentsFilePath(path, root, agentDir))
+                continue;
+            const content = await readResolvedContextFile(path, file.content, resolvedRoot, resolvedAgentDir);
+            if (content === undefined)
+                continue;
+            loadedFiles.push({
+                path,
+                content,
+            });
+        }
+        return loadedFiles;
+    }
+    async findAvailableAgentsFiles(root, loadedFiles) {
+        const loadedPaths = new Set(loadedFiles.map((file) => resolve(file.path)));
+        const loadedRealPaths = new Set();
+        for (const file of loadedFiles) {
+            const realPath = await tryRealpath(file.path);
+            if (realPath)
+                loadedRealPaths.add(realPath);
+        }
+        const discovered = [];
+        await walkWorkspace(root, async (path, entry) => {
+            if (!entry.isFile())
+                return;
+            if (!CONTEXT_FILE_NAMES.has(entry.name))
+                return;
+            if (loadedPaths.has(path))
+                return;
+            const realPath = await tryRealpath(path);
+            if (realPath && loadedRealPaths.has(realPath))
+                return;
+            discovered.push({ path });
+        });
+        return discovered.sort((a, b) => a.path.localeCompare(b.path));
+    }
+}
+async function canonicalPath(path) {
+    const missingSegments = [];
+    let candidate = path;
+    while (true) {
+        try {
+            return resolve(await realpath(candidate), ...missingSegments.slice().reverse());
+        }
+        catch (error) {
+            if (!isErrnoException(error) || (error.code !== "ENOENT" && error.code !== "ENOTDIR")) {
+                throw error;
+            }
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return path;
+            missingSegments.push(basename(candidate));
+            candidate = parent;
+        }
+    }
+}
+export async function ensureCheckoutWorkspaceRoot(path, ops = { stat, mkdir }) {
+    try {
+        return await ops.stat(path);
+    }
+    catch (error) {
+        if (!isErrnoException(error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    await ops.mkdir(path, { recursive: true });
+    return await ops.stat(path);
+}
+const CONTEXT_FILE_NAMES = new Set(["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
+const SKIPPED_CONTEXT_DIRS = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".forgerelay",
+    ".devspace",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+export function formatAgentsPath(path, workspaceRoot) {
+    if (!workspaceRoot)
+        return path.split(sep).join("/");
+    const relationship = relative(workspaceRoot, path);
+    if (relationship === "" ||
+        relationship.startsWith("..") ||
+        relationship === ".." ||
+        relationship.includes(`..${sep}`)) {
+        return path.split(sep).join("/");
+    }
+    return relationship.split(sep).join("/");
+}
+function isInitialAgentsFilePath(path, root, agentDir) {
+    if (isPathInsideRoot(path, agentDir))
+        return true;
+    return isPathInsideRoot(path, root) && dirname(path) === root;
+}
+async function readResolvedContextFile(path, fallbackContent, root, agentDir) {
+    try {
+        const resolvedPath = await realpath(path);
+        if (!isInitialAgentsFilePath(resolvedPath, root, agentDir))
+            return undefined;
+        return await readFile(resolvedPath, "utf8");
+    }
+    catch {
+        return fallbackContent;
+    }
+}
+async function tryRealpath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function walkWorkspace(directory, visit) {
+    let entries;
+    try {
+        entries = await opendir(directory);
+    }
+    catch {
+        return;
+    }
+    for await (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIPPED_CONTEXT_DIRS.has(entry.name)) {
+                await walkWorkspace(path, visit);
+            }
+            continue;
+        }
+        await visit(path, entry);
+    }
+}
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}

package/docs/agent-profile-schema.md

@@ -0,0 +1,119 @@
+# ForgeRelay Agent Profile Schema
+
+ForgeRelay agent profiles are user-owned Markdown files with YAML frontmatter.
+ForgeRelay owns provider invocation; the profile describes which local coding
+runtime to use and what prompt prefix/configuration to apply.
+
+## Locations
+
+New locations:
+
+```text
+~/.forgerelay/agents/*.md
+.forgerelay/agents/*.md
+```
+
+Migration compatibility:
+
+```text
+~/.devspace/agents/*.md
+.devspace/agents/*.md
+```
+
+When an existing legacy config directory is reused, its global `agents` folder
+remains active automatically.
+
+## Example
+
+```markdown
+---
+schema: forgerelay-agent/v1
+name: reviewer
+description: Review changes for correctness and regressions.
+provider: codex
+model: gpt-5.6-codex
+thinking: high
+---
+
+Review the requested implementation. Focus on correctness, regression risk,
+and missing tests. Return concrete findings before optional suggestions.
+```
+
+The `schema` field is descriptive/versioning metadata for profile authors. The
+current parser focuses on the supported operational fields below.
+
+## Fields
+
+### `name`
+
+Optional. Use lowercase kebab-case when practical. If omitted, ForgeRelay uses
+the filename without `.md`.
+
+### `description`
+
+Optional but recommended. This is shown in the compact profile catalog returned
+to the MCP host.
+
+### `provider`
+
+Required. Currently supported provider identifiers are:
+
+```text
+codex
+claude
+opencode
+pi
+cursor
+copilot
+```
+
+Custom provider strings are rejected. ForgeRelay maps these identifiers through
+its local provider adapter registry.
+
+### `model`
+
+Optional provider-specific model value. If omitted, the provider default
+applies.
+
+### `thinking`
+
+Optional provider-specific reasoning/thinking control. ForgeRelay passes through
+supported values rather than translating names between providers.
+
+### `disabled`
+
+Optional boolean. `true` excludes the profile from the active catalog.
+
+## Prompt body
+
+The Markdown body after frontmatter is the profile prompt prefix ForgeRelay
+prepends when launching the provider-backed worker.
+
+Keep reusable worker policy here; keep task-specific instructions in the prompt
+supplied to the `run` command/tool.
+
+## Current CLI workflow
+
+```bash
+forgerelay agents ls
+forgerelay agents run <profile-or-provider-or-id> "<prompt>"
+forgerelay agents show <id>
+```
+
+Optional provider overrides include:
+
+```bash
+forgerelay agents run <profile> --model <model> "<prompt>"
+forgerelay agents run <profile> --thinking <level> "<prompt>"
+```
+
+`agents ls` lists existing subagent sessions for the current workspace; it is
+not the profile-definition catalog. The compact profile catalog is returned by
+`open_workspace` when subagents are enabled.
+
+## MCP direction
+
+Profiles and provider execution are intentionally independent of the current
+CLI transport. A planned first-class MCP subagent tool will wrap the same
+provider adapter/session registry rather than introducing a second agent
+runtime.