@akira-tl/forgerelay 0.1.0

package/examples/agents/codex-qa-tester.md

@@ -0,0 +1,29 @@
+---
+schema: forgerelay-agent/v1
+name: codex-qa-tester
+description: Manual QA profile for browser testing, workflow verification, and regression checks.
+provider: codex
+model: gpt-5.4-mini
+thinking: high
+---
+
+Verify the requested user workflow from the outside, like a QA pass before
+release. Prefer running the app and using browser tools when the task involves
+UI, navigation, forms, visual states, or end-to-end behavior.
+
+- Do not modify files.
+- Start from the acceptance criteria in the prompt; turn vague requests into a small checklist.
+- Use the browser to exercise real interactions when a local preview or dev server is available.
+- Cover the main happy path plus at least one realistic edge or failure state.
+- Capture exact reproduction steps for every issue found.
+- Distinguish confirmed failures from untested risks.
+
+Report:
+
+```text
+qa_summary:
+checks_run:
+issues_found:
+reproduction_steps:
+untested_risks:
+```

package/examples/agents/codex-worker.md

@@ -0,0 +1,25 @@
+---
+schema: forgerelay-agent/v1
+name: codex-worker
+description: Implementation profile for focused coding tasks with clear acceptance criteria.
+provider: codex
+model: gpt-5.4
+---
+
+Implement the requested change with minimal surface area. Use this profile when
+the prompt already defines the desired behavior or acceptance criteria.
+
+- Read nearby code before editing.
+- Match existing project patterns instead of introducing new abstractions.
+- Keep unrelated files, formatting, and dependency metadata untouched.
+- Prefer targeted tests for the changed behavior.
+- Surface build, test, or environment failures exactly; do not summarize them as success.
+
+Report:
+
+```text
+summary:
+tests_run:
+blockers:
+notes:
+```

package/examples/agents/copilot-reviewer.md

@@ -0,0 +1,25 @@
+---
+schema: forgerelay-agent/v1
+name: copilot-reviewer
+description: Read-only review profile for bug risk, regressions, and missing test coverage.
+provider: copilot
+---
+
+Review the requested code path or diff without editing. Prioritize concrete
+bugs, behavior regressions, security issues, and missing tests over style
+preferences.
+
+- Do not modify files.
+- Lead with findings ordered by severity.
+- Tie each finding to a specific file, symbol, or behavior.
+- Ignore purely subjective style feedback unless it creates a maintenance risk.
+- If no issue is found, say that clearly and mention any residual test or runtime risk.
+
+Report:
+
+```text
+findings:
+evidence:
+test_gaps:
+residual_risk:
+```

package/examples/agents/cursor-agent-worker.md

@@ -0,0 +1,26 @@
+---
+schema: forgerelay-agent/v1
+name: cursor-agent-worker
+description: Implementation profile for UI-heavy changes, small refactors, and alternative solution passes.
+provider: cursor
+model: composer-2.5-fast
+---
+
+Work on the requested change with a bias toward practical, shippable edits. This
+profile is useful for UI polish, small refactors, and trying an alternate
+implementation path.
+
+- Keep edits scoped to the requested workflow or component.
+- Preserve existing visual language and interaction patterns.
+- Avoid changing data contracts or public APIs unless the prompt asks for it.
+- Check responsive and empty/error states when touching UI.
+- Report what was verified and what still needs a human look.
+
+Report:
+
+```text
+summary:
+verification:
+blockers:
+open_questions:
+```

package/examples/agents/opencode-explorer.md

@@ -0,0 +1,27 @@
+---
+schema: forgerelay-agent/v1
+name: opencode-explorer
+description: Read-only profile for fast relevant-file discovery and small architecture questions.
+provider: opencode
+model: opencode/deepseek-v4-flash-free
+thinking: high
+---
+
+Find the answer quickly without editing. Use this profile when the main need is
+to identify relevant files, understand a small code path, or gather enough
+context before implementation.
+
+- Do not modify files.
+- Search first, then read only the files needed to answer the prompt.
+- Prefer precise file paths and symbols over broad summaries.
+- Keep the response short unless the code path is genuinely complex.
+- State uncertainty when evidence is incomplete.
+
+Report:
+
+```text
+answer:
+evidence:
+relevant_files:
+unknowns:
+```

package/examples/agents/pi-reviewer.md

@@ -0,0 +1,27 @@
+---
+schema: forgerelay-agent/v1
+name: pi-reviewer
+description: Read-only review profile for quick risk checks and targeted implementation questions.
+provider: pi
+model: openai-codex/gpt-5.5
+thinking: high
+---
+
+Review or investigate only the area requested. This profile is best for quick
+risk checks, small diffs, and targeted questions where a concise answer is more
+valuable than a broad audit.
+
+- Do not modify files.
+- Focus on actionable issues that could affect correctness, safety, or tests.
+- Cite the specific code evidence for each point.
+- Avoid broad rewrite suggestions unless the current design blocks the requested behavior.
+- Keep low-confidence observations under `unknowns`.
+
+Report:
+
+```text
+findings:
+evidence:
+risk_level:
+unknowns:
+```

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@akira-tl/forgerelay",
+  "version": "0.1.0",
+  "description": "Local development control plane for MCP coding agents.",
+  "type": "module",
+  "homepage": "https://github.com/Akira-TL/forgerelay#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Akira-TL/forgerelay.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Akira-TL/forgerelay/issues"
+  },
+  "main": "dist/server.js",
+  "engines": {
+    "node": ">=22.19 <27"
+  },
+  "bin": {
+    "forgerelay": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs/*.md",
+    "examples",
+    "scripts",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "NOTICE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json",
+    "build:app": "vite build",
+    "dev": "node scripts/dev-server.mjs",
+    "postinstall": "node scripts/fix-node-pty-permissions.mjs",
+    "start": "node dist/cli.js serve",
+    "test": "tsx src/config.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "release:check": "node scripts/release-version.mjs check",
+    "release:tag-check": "node scripts/release-version.mjs tag",
+    "release:next": "node scripts/release-version.mjs next patch",
+    "release:patch": "node scripts/release-version.mjs next patch",
+    "release:minor": "node scripts/release-version.mjs next minor",
+    "release:major": "node scripts/release-version.mjs next major",
+    "release:verify": "npm run release:check && npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "chatgpt",
+    "coding-agent",
+    "developer-tools",
+    "git-worktree"
+  ],
+  "author": "Akira-TL",
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.1.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.200",
+    "@clack/prompts": "^1.5.1",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@modelcontextprotocol/ext-apps": "^1.7.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openai/codex-sdk": "^0.142.5",
+    "@opencode-ai/sdk": "^1.17.13",
+    "@pierre/diffs": "^1.2.5",
+    "better-sqlite3": "^12.10.0",
+    "diff": "^8.0.3",
+    "drizzle-orm": "^0.45.2",
+    "express": "^5.2.1",
+    "lucide": "^1.24.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "semver": "^7.8.4",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@types/semver": "^7.7.1",
+    "@vitejs/plugin-react": "^6.0.2",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.14"
+  },
+  "overrides": {
+    "protobufjs": "7.6.4",
+    "ws": "8.21.0",
+    "undici": "8.5.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  }
+}

package/scripts/dev-server.mjs

@@ -0,0 +1,120 @@
+import { spawn } from "node:child_process";
+import { readdirSync, statSync, watch } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const watchRoots = ["src"].map((entry) => join(repoRoot, entry));
+const restartDelayMs = 750;
+const crashDelayMs = 1500;
+
+let child;
+let restartTimer;
+let stoppingForRestart = false;
+let shuttingDown = false;
+
+function log(message) {
+  console.error(`[forgerelay:dev] ${message}`);
+}
+
+function start() {
+  stoppingForRestart = false;
+  child = spawn("npx", ["tsx", "src/cli.ts", "serve"], {
+    cwd: repoRoot,
+    env: process.env,
+    stdio: "inherit",
+  });
+
+  child.on("exit", (code, signal) => {
+    child = undefined;
+    if (shuttingDown) return;
+    if (stoppingForRestart) return;
+
+    log(`server exited (${signal ?? code ?? "unknown"}); restarting in ${crashDelayMs}ms`);
+    scheduleRestart(crashDelayMs);
+  });
+}
+
+function scheduleRestart(delayMs = restartDelayMs) {
+  clearTimeout(restartTimer);
+  restartTimer = setTimeout(restart, delayMs);
+}
+
+function restart() {
+  if (shuttingDown) return;
+  clearTimeout(restartTimer);
+
+  if (!child) {
+    start();
+    return;
+  }
+
+  stoppingForRestart = true;
+  child.once("exit", () => {
+    if (!shuttingDown) start();
+  });
+  child.kill("SIGTERM");
+
+  setTimeout(() => {
+    if (child && stoppingForRestart) child.kill("SIGKILL");
+  }, 3000).unref();
+}
+
+function watchDirectory(root) {
+  const watchers = [];
+  const seen = new Set();
+
+  function addDirectory(dir) {
+    if (seen.has(dir)) return;
+    seen.add(dir);
+
+    const watcher = watch(dir, (event, filename) => {
+      if (!filename) {
+        scheduleRestart();
+        return;
+      }
+
+      const path = join(dir, filename.toString());
+      if (event === "rename") maybeAddDirectory(path);
+      scheduleRestart();
+    });
+    watchers.push(watcher);
+
+    for (const entry of readdirSync(dir)) {
+      maybeAddDirectory(join(dir, entry));
+    }
+  }
+
+  function maybeAddDirectory(path) {
+    try {
+      const stats = statSync(path);
+      if (stats.isDirectory()) addDirectory(path);
+    } catch {
+      // The file may have been deleted between the watch event and stat call.
+    }
+  }
+
+  addDirectory(root);
+  return watchers;
+}
+
+function shutdown() {
+  shuttingDown = true;
+  clearTimeout(restartTimer);
+  if (!child) return process.exit(0);
+
+  child.once("exit", () => process.exit(0));
+  child.kill("SIGTERM");
+  setTimeout(() => process.exit(1), 3000).unref();
+}
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, shutdown);
+}
+
+for (const root of watchRoots) {
+  watchDirectory(root);
+}
+
+log("watching src; server restarts on changes and after crashes");
+start();

package/scripts/fix-node-pty-permissions.mjs

@@ -0,0 +1,22 @@
+import { chmod } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.platform === "darwin") {
+  const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  for (const architecture of ["arm64", "x64"]) {
+    const helper = resolve(
+      projectRoot,
+      "node_modules",
+      "node-pty",
+      "prebuilds",
+      `darwin-${architecture}`,
+      "spawn-helper",
+    );
+    try {
+      await chmod(helper, 0o755);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}

package/scripts/release-version.mjs

@@ -0,0 +1,207 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const packagePath = resolve(repoRoot, "package.json");
+const lockPath = resolve(repoRoot, "package-lock.json");
+const changelogPath = resolve(repoRoot, "CHANGELOG.md");
+const noticePath = resolve(repoRoot, "NOTICE.md");
+const licensePath = resolve(repoRoot, "LICENSE");
+const stableVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const expectedPackageName = "@akira-tl/forgerelay";
+const expectedRepositoryUrl = "git+https://github.com/Akira-TL/forgerelay.git";
+const expectedHomepage = "https://github.com/Akira-TL/forgerelay#readme";
+const expectedBugsUrl = "https://github.com/Akira-TL/forgerelay/issues";
+
+const [command = "check", argument, ...rest] = process.argv.slice(2);
+const dryRun = rest.includes("--dry-run") || argument === "--dry-run";
+const value = argument === "--dry-run" ? undefined : argument;
+const state = await readState();
+
+switch (command) {
+  case "check":
+    checkState(state);
+    console.log(`release metadata is consistent at ${state.pkg.version}`);
+    break;
+  case "tag": {
+    checkState(state);
+    if (!value) fail("usage: node scripts/release-version.mjs tag vX.Y.Z");
+    if (getUnreleasedBody(state.changelog)) {
+      fail("CHANGELOG.md still has Unreleased changes; prepare the next version before creating a release tag");
+    }
+    const expectedTag = `v${state.pkg.version}`;
+    if (value !== expectedTag) {
+      fail(`tag ${JSON.stringify(value)} does not match package version; expected ${expectedTag}`);
+    }
+    console.log(`release tag ${value} matches package version and changelog`);
+    break;
+  }
+  case "next": {
+    checkState(state);
+    const bump = value ?? "patch";
+    if (!new Set(["patch", "minor", "major"]).has(bump)) {
+      fail("usage: node scripts/release-version.mjs next [patch|minor|major] [--dry-run]");
+    }
+    await prepareRelease(state, incrementVersion(state.pkg.version, bump), dryRun);
+    break;
+  }
+  default:
+    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, or next`);
+}
+
+async function readState() {
+  const [packageText, lockText, changelog, notice, license] = await Promise.all([
+    readFile(packagePath, "utf8"),
+    readFile(lockPath, "utf8"),
+    readFile(changelogPath, "utf8"),
+    readFile(noticePath, "utf8"),
+    readFile(licensePath, "utf8"),
+  ]);
+
+  return {
+    packageText,
+    lockText,
+    changelog,
+    notice,
+    license,
+    pkg: JSON.parse(packageText),
+    lock: JSON.parse(lockText),
+  };
+}
+
+function checkState(state) {
+  const version = state.pkg.version;
+  if (state.pkg.name !== expectedPackageName) {
+    fail(`unexpected package name ${JSON.stringify(state.pkg.name)}; expected ${expectedPackageName}`);
+  }
+  if (typeof version !== "string" || !stableVersionPattern.test(version)) {
+    fail(`package version ${JSON.stringify(version)} must be a stable X.Y.Z version`);
+  }
+  if (state.pkg.repository?.url !== expectedRepositoryUrl) {
+    fail(`package repository.url must be ${expectedRepositoryUrl} for GitHub/npm trusted publishing`);
+  }
+  if (state.pkg.homepage !== expectedHomepage) {
+    fail(`package homepage must be ${expectedHomepage}`);
+  }
+  if (state.pkg.bugs?.url !== expectedBugsUrl) {
+    fail(`package bugs.url must be ${expectedBugsUrl}`);
+  }
+  if (state.pkg.publishConfig?.access !== "public") {
+    fail("package publishConfig.access must be public");
+  }
+  if (state.pkg.publishConfig?.tag !== "latest") {
+    fail("package publishConfig.tag must be latest");
+  }
+  if (state.pkg.bin?.forgerelay !== "dist/cli.js") {
+    fail("package bin.forgerelay must point to dist/cli.js");
+  }
+  if (state.lock.name !== expectedPackageName || state.lock.version !== version) {
+    fail("package-lock.json root name/version does not match package.json");
+  }
+  if (state.lock.packages?.[""]?.name !== expectedPackageName || state.lock.packages?.[""]?.version !== version) {
+    fail("package-lock root package name/version does not match package.json");
+  }
+  if (!state.changelog.includes("## [Unreleased]")) {
+    fail("CHANGELOG.md is missing ## [Unreleased]");
+  }
+  if (!state.changelog.includes(`## [${version}]`)) {
+    fail(`CHANGELOG.md is missing the current release heading ## [${version}]`);
+  }
+  checkAttribution(state);
+}
+
+function checkAttribution(state) {
+  if (!state.license.includes("Copyright (c) 2026 Waishnav")) {
+    fail("LICENSE must preserve the upstream Waishnav copyright notice");
+  }
+  if (!state.license.includes("Copyright (c) 2026 Akira-TL, modifications")) {
+    fail("LICENSE must identify Akira-TL modifications");
+  }
+  if (!state.notice.includes("https://github.com/Waishnav/devspace")) {
+    fail("NOTICE.md must identify the upstream DevSpace repository");
+  }
+  if (!state.notice.includes("independently maintained by Akira-TL")) {
+    fail("NOTICE.md must identify this distribution as independently maintained by Akira-TL");
+  }
+  if (!state.pkg.files?.includes("NOTICE.md")) {
+    fail("package files must include NOTICE.md");
+  }
+}
+
+async function prepareRelease(state, nextVersion, dryRun) {
+  const nextChangelog = promoteUnreleased(state.changelog, nextVersion);
+  const nextPackage = { ...state.pkg, version: nextVersion };
+  const nextLock = structuredClone(state.lock);
+  nextLock.version = nextVersion;
+  nextLock.packages[""].version = nextVersion;
+
+  if (dryRun) {
+    console.log(`${state.pkg.version} -> ${nextVersion}`);
+    console.log("dry run only; no files changed");
+    return;
+  }
+
+  await Promise.all([
+    writeFile(packagePath, `${JSON.stringify(nextPackage, null, 2)}\n`),
+    writeFile(lockPath, `${JSON.stringify(nextLock, null, 2)}\n`),
+    writeFile(changelogPath, nextChangelog),
+  ]);
+
+  console.log(`${state.pkg.version} -> ${nextVersion}`);
+  console.log("updated package.json, package-lock.json, and CHANGELOG.md");
+  console.log("next: review the diff, run npm run release:verify, commit, then push the matching vX.Y.Z tag");
+}
+
+function promoteUnreleased(changelog, nextVersion) {
+  const unreleasedBody = getUnreleasedBody(changelog);
+  if (!unreleasedBody) {
+    fail("CHANGELOG.md Unreleased section is empty; add release notes before preparing a release");
+  }
+  if (changelog.includes(`## [${nextVersion}]`)) {
+    fail(`CHANGELOG.md already contains release ${nextVersion}`);
+  }
+
+  const heading = "## [Unreleased]";
+  const headingIndex = changelog.indexOf(heading);
+  const bodyStart = headingIndex + heading.length;
+  const nextHeadingIndex = changelog.indexOf("\n## [", bodyStart);
+  const bodyEnd = nextHeadingIndex < 0 ? changelog.length : nextHeadingIndex;
+  const date = new Date().toISOString().slice(0, 10);
+  const replacement = `${heading}\n\n## [${nextVersion}] - ${date}\n\n${unreleasedBody}\n`;
+  return `${changelog.slice(0, headingIndex)}${replacement}${changelog.slice(bodyEnd)}`;
+}
+
+function getUnreleasedBody(changelog) {
+  const heading = "## [Unreleased]";
+  const headingIndex = changelog.indexOf(heading);
+  if (headingIndex < 0) return "";
+  const bodyStart = headingIndex + heading.length;
+  const nextHeadingIndex = changelog.indexOf("\n## [", bodyStart);
+  const bodyEnd = nextHeadingIndex < 0 ? changelog.length : nextHeadingIndex;
+  return changelog.slice(bodyStart, bodyEnd).trim();
+}
+
+function incrementVersion(version, bump) {
+  const match = version.match(stableVersionPattern);
+  if (!match) fail(`cannot increment invalid stable version ${JSON.stringify(version)}`);
+  let major = Number(match[1]);
+  let minor = Number(match[2]);
+  let patch = Number(match[3]);
+  if (bump === "major") {
+    major += 1;
+    minor = 0;
+    patch = 0;
+  } else if (bump === "minor") {
+    minor += 1;
+    patch = 0;
+  } else {
+    patch += 1;
+  }
+  return `${major}.${minor}.${patch}`;
+}
+
+function fail(message) {
+  console.error(`release-version: ${message}`);
+  process.exit(1);
+}