@khanglvm/relay 0.7.0 → 0.8.1

package/README.md

@@ -25,42 +25,42 @@ npm i -g @khanglvm/relay
 # the agent skill → every detected agent (Claude Code, Codex, Cursor, …)
 npx skills add khanglvm/relay --skill relay --all
 
-# enforce it (recommended) — a skill alone is an ignorable hint; append relay's
-# short usage rules to your agent's global instructions (per-agent commands below)
-rly skill rules
+# enforce it (recommended) — a skill alone is an ignorable hint. `rly install`
+# writes relay's short usage rules into the right file for each agent (details below):
+rly install --all          # every agent detected on this machine
 ```
 
 That's it. Next time your agent needs a decision or wants to show you a plan,
 it opens a board like the ones above and waits for your Submit.
 
+Keep relay current with **`rly upgrade`** — it installs the latest CLI and
+refreshes the skill in one step, leaving any boards you have open untouched.
+
 ### Tell your agent to actually use it
 
-`rly skill rules` prints relay's short usage rules. A skill is just an ignorable
-hint — these rules in the file your agent *always* reads are what make it reach for
-relay. Append them to your agent's **global** instructions:
+A skill is just an ignorable hint — relay's short usage rules in the file your
+agent *always* reads are what make it reach for relay. **`rly install` writes
+those rules into the right file for each agent**, cross-platform (macOS / Linux /
+Windows):
 
 ```sh
-rly skill rules >> ~/.claude/CLAUDE.md          # Claude Code
-rly skill rules >> ~/.codex/AGENTS.md           # Codex
-rly skill rules >> ~/.gemini/GEMINI.md          # Gemini CLI
-rly skill rules >> ~/.config/opencode/AGENTS.md # OpenCode
+rly install --all                # every agent detected on this machine
+rly install --target claude      # → ~/.claude/CLAUDE.md
+rly install --target cursor      # → .cursor/rules/relay.mdc (with frontmatter)
+rly install --target copilot     # → .github/copilot-instructions.md (+ JetBrains global)
+rly install                      # no target: print the agent → file map for your OS
 ```
 
-Cursor and GitHub Copilot keep global rules in a settings panel, not a file — run
-`rly skill rules` and paste the output into Cursor's *Settings → Rules → User Rules*
-or Copilot's custom-instructions.
-
-<details>
-<summary>More agents</summary>
-
-```sh
-rly skill rules >> ~/.codeium/windsurf/memories/global_rules.md # Windsurf
-rly skill rules >> ~/.factory/AGENTS.md                         # Droid (Factory)
-```
+Supported targets: `claude`, `codex`, `cursor`, `copilot` (VS Code / Visual Studio /
+JetBrains), `kiro`, `windsurf`, `cline`, `gemini`, `opencode`, `droid` (Factory), and
+the generic `agents` (`AGENTS.md`). Flags: `--scope global|project` (where the rules
+land), `--print` (emit the text + resolved path for manual copy/paste), `--list`.
+relay's block is marker-delimited and idempotent — re-running updates only that block
+and leaves the rest of your file alone.
 
-Any other agent: run `rly skill rules` and paste the block into whatever file or
-settings panel it reads as global instructions.
-</details>
+Using an agent that isn't listed? `rly skill rules` prints the block to paste into
+whatever file or settings panel it reads — e.g. Cursor's *Settings → Rules → User
+Rules* or Copilot's custom instructions (their *user-level* rules aren't file-based).
 
 ## What it improves
 
@@ -82,6 +82,8 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 | | |
 |---|---|
 | `rly help` | every command at a glance |
+| `rly install --target <agent>` | write relay's rules into an agent's instruction file — `claude` `codex` `cursor` `copilot` `kiro` `windsurf` `cline` `gemini` `opencode` `droid` `agents`; `--all`, `--scope`, `--print`, `--list` |
+| `rly upgrade` | update the CLI **and** refresh the skill in one step (safe around open boards; `--dry-run`, `--cli-only`, `--skill-only`) |
 | `rly agent` | the full agent guide — spec format, all block types, annotations, patterns ([docs/AGENT.md](docs/AGENT.md)) |
 | `rly schema` | board spec JSON Schema |
 | [skills/relay/SKILL.md](skills/relay/SKILL.md) | the bundled skill |
@@ -94,6 +96,28 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 
 ## Changelog
 
+### 0.8.1
+- `rly install` adds **OpenCode** (`~/.config/opencode/AGENTS.md`) and **Droid /
+  Factory** (`~/.factory/AGENTS.md`) targets.
+- README documents `rly install` and `rly upgrade`.
+
+### 0.8.0 — install into any agent
+- **`rly install --target <agent>`** writes relay's usage rules into the right
+  file for Claude Code, Codex, Cursor, GitHub Copilot (VS Code / Visual Studio /
+  JetBrains), Kiro, Windsurf, Cline, Gemini, or the generic `AGENTS.md` —
+  cross-platform (macOS / Linux / Windows), idempotent, with `--all`, `--scope`,
+  and `--print`.
+- Fixed `rly skill install` crashing when the target skill dir was a symlink.
+
+### 0.7.0 — sturdier boards, self-update
+- **Markdown blocks render GFM tables**; element comments moved to an
+  Outline-style right sidebar with inline highlights on commented text.
+- **Seamless timeouts** — a detached board that runs past its deadline keeps
+  serving so you can still submit (it lands as `submitted`); the page shows a
+  calm note instead of disconnecting.
+- **`rly upgrade`** — install the latest CLI and refresh the skill in one step.
+- Per-question notes are multi-line textboxes.
+
 ### 0.6.0 — comment on anything
 - **Comment on any part of a custom-HTML mockup.** Hover any element — a heading,
   a button, a card, the price — and a pin appears to leave an inline note. No

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, sandboxed HTML) and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
   "keywords": [
     "ai-agents",

package/src/cli.js

@@ -30,7 +30,7 @@ const PKG_NAME = PKG_JSON.name; // e.g. "@khanglvm/relay" — the global package
 const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
   'submit-label', 'height', 'limit', 'target', 'id', 'replies',
-  'on-result', 'notify-cmd', 'idle-grace',
+  'on-result', 'notify-cmd', 'idle-grace', 'scope',
 ]);
 
 function camel(key) {
@@ -771,6 +771,11 @@ function cmdSkill(rest) {
     const installed = [];
     for (const t of targets) {
       fs.mkdirSync(path.dirname(t), { recursive: true });
+      // Clear whatever is already there first. cpSync refuses to overwrite a
+      // non-directory (a symlink or file at the target — e.g. a skill dir the
+      // user symlinked elsewhere) with a directory, so a plain re-install would
+      // crash. rmSync on a symlink removes the link itself, not its target.
+      fs.rmSync(t, { recursive: true, force: true });
       fs.cpSync(SKILL_SRC, t, { recursive: true });
       fs.writeFileSync(path.join(t, '.rly-version'), VERSION);
       installed.push(t);
@@ -795,6 +800,196 @@ Full guide: \`rly agent\`.`);
   return 0;
 }
 
+// ===========================================================================
+// `rly install` — inject relay's always-read rules into ANY agent's
+// instruction file, cross-platform. `rly skill install` (above) handles the
+// full SKILL.md for skill-aware agents; this covers the long tail (Cursor,
+// Copilot, Kiro, Windsurf, Cline, Gemini, generic AGENTS.md, …) that read a
+// rules/instructions/steering/context markdown file instead.
+// ===========================================================================
+
+const RELAY_BEGIN = '<!-- relay:begin (managed by `rly install` — your edits outside these markers are kept) -->';
+const RELAY_END = '<!-- relay:end -->';
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Resolve OS-specific base dirs from an injectable env/home/platform so the
+// path logic is unit-testable for win32 / linux / darwin without running there.
+function platformDirs({ platform, home, env }) {
+  const xdg = env.XDG_CONFIG_HOME || path.join(home, '.config');
+  const localApp = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  // Copilot-in-JetBrains global instructions dir.
+  const jetbrainsCopilot = platform === 'win32'
+    ? path.join(localApp, 'github-copilot', 'intellij')
+    : path.join(xdg, 'github-copilot', 'intellij');
+  return { xdg, jetbrainsCopilot, documents: path.join(home, 'Documents') };
+}
+
+// The relay instruction registry. Each agent declares how to install relay's
+// rules at `global` (user, machine-wide) and/or `project` (cwd) scope, in what
+// `style`, and a `detect` dir whose existence means "you use this agent"
+// (drives `--all`). Styles:
+//   'shared'    — upsert a marked block into a possibly-shared file (CLAUDE.md,
+//                 AGENTS.md, copilot-instructions.md, …); your other content is
+//                 preserved, only relay's block is rewritten.
+//   'dedicated' — relay owns the whole file (.kiro/steering, .windsurf/rules,
+//                 .clinerules, …); safe to overwrite.
+//   'mdc'       — dedicated, with Cursor `.mdc` YAML frontmatter.
+export function agentRegistry({ platform = process.platform, home = os.homedir(), cwd = process.cwd(), env = process.env } = {}) {
+  const d = platformDirs({ platform, home, env });
+  const j = path.join;
+  return [
+    { id: 'claude', label: 'Claude Code',
+      detect: j(home, '.claude'),
+      global: { file: j(home, '.claude', 'CLAUDE.md'), style: 'shared' },
+      project: { file: j(cwd, 'CLAUDE.md'), style: 'shared' },
+      note: 'full skill: `rly skill install`' },
+    { id: 'codex', label: 'OpenAI Codex',
+      detect: j(home, '.codex'),
+      global: { file: j(home, '.codex', 'AGENTS.md'), style: 'shared' },
+      project: { file: j(cwd, 'AGENTS.md'), style: 'shared' } },
+    { id: 'agents', label: 'AGENTS.md standard (Amp, Jules, Cline, …)',
+      detect: j(home, '.agents'),
+      global: { file: j(home, '.agents', 'AGENTS.md'), style: 'shared' },
+      project: { file: j(cwd, 'AGENTS.md'), style: 'shared' } },
+    { id: 'cursor', label: 'Cursor',
+      detect: j(home, '.cursor'),
+      global: null, // user rules are set in Cursor Settings UI (not file-based)
+      project: { file: j(cwd, '.cursor', 'rules', 'relay.mdc'), style: 'mdc' },
+      note: 'global "User Rules" are set in Settings UI, not a file' },
+    { id: 'copilot', label: 'GitHub Copilot (VS Code / Visual Studio / JetBrains)',
+      detect: path.dirname(d.jetbrainsCopilot), // …/github-copilot
+      global: { file: j(d.jetbrainsCopilot, 'global-copilot-instructions.md'), style: 'shared' },
+      project: { file: j(cwd, '.github', 'copilot-instructions.md'), style: 'shared' },
+      note: 'global file applies in JetBrains IDEs; project file applies everywhere' },
+    { id: 'kiro', label: 'Kiro',
+      detect: j(home, '.kiro'),
+      global: { file: j(home, '.kiro', 'steering', 'relay.md'), style: 'dedicated' },
+      project: { file: j(cwd, '.kiro', 'steering', 'relay.md'), style: 'dedicated' } },
+    { id: 'windsurf', label: 'Windsurf',
+      detect: j(home, '.codeium'),
+      global: { file: j(home, '.codeium', 'windsurf', 'memories', 'global_rules.md'), style: 'shared' },
+      project: { file: j(cwd, '.windsurf', 'rules', 'relay.md'), style: 'dedicated' } },
+    { id: 'cline', label: 'Cline',
+      detect: j(d.documents, 'Cline'),
+      global: { file: j(d.documents, 'Cline', 'Rules', 'relay.md'), style: 'dedicated' },
+      project: { file: j(cwd, '.clinerules', 'relay.md'), style: 'dedicated' } },
+    { id: 'gemini', label: 'Gemini CLI',
+      detect: j(home, '.gemini'),
+      global: { file: j(home, '.gemini', 'GEMINI.md'), style: 'shared' },
+      project: { file: j(cwd, 'GEMINI.md'), style: 'shared' } },
+    { id: 'opencode', label: 'OpenCode',
+      detect: j(d.xdg, 'opencode'),
+      global: { file: j(d.xdg, 'opencode', 'AGENTS.md'), style: 'shared' },
+      project: { file: j(cwd, 'AGENTS.md'), style: 'shared' } },
+    { id: 'droid', label: 'Droid (Factory)',
+      detect: j(home, '.factory'),
+      global: { file: j(home, '.factory', 'AGENTS.md'), style: 'shared' },
+      project: { file: j(cwd, 'AGENTS.md'), style: 'shared' } },
+  ];
+}
+
+// Render the relay rules in the style the target file expects.
+function renderInstruction(style) {
+  if (style === 'mdc') {
+    return `---\ndescription: relay — collect decisions & show rich visuals in the browser, not the terminal\nalwaysApply: true\n---\n\n${SKILL_RULES}\n`;
+  }
+  return `${SKILL_RULES}\n`; // dedicated file — relay owns it
+}
+
+// Upsert relay's marked block into a (possibly shared / pre-existing) file,
+// leaving everything outside the markers untouched. Returns 'added'|'updated'.
+function upsertBlock(file, body) {
+  let existing = '';
+  try { existing = fs.readFileSync(file, 'utf8'); } catch { /* new file */ }
+  const wrapped = `${RELAY_BEGIN}\n${body}\n${RELAY_END}`;
+  const re = new RegExp(escapeRegExp(RELAY_BEGIN) + '[\\s\\S]*?' + escapeRegExp(RELAY_END));
+  const had = re.test(existing);
+  const next = had
+    ? existing.replace(re, wrapped)
+    : (existing.trim() ? existing.replace(/\s*$/, '') + '\n\n' + wrapped + '\n' : wrapped + '\n');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  return had ? 'updated' : 'added';
+}
+
+function writeInstruction(target) {
+  if (target.style === 'shared') return upsertBlock(target.file, SKILL_RULES);
+  const existed = fs.existsSync(target.file);
+  fs.mkdirSync(path.dirname(target.file), { recursive: true });
+  fs.writeFileSync(target.file, renderInstruction(target.style));
+  return existed ? 'updated' : 'added';
+}
+
+function cmdInstall(args) {
+  const reg = agentRegistry();
+  const byId = Object.fromEntries(reg.map((a) => [a.id, a]));
+  const scope = args.scope === 'project' ? 'project' : args.scope === 'global' ? 'global' : null;
+
+  // Pick the target for an agent: explicit --scope wins; else prefer global
+  // (machine-wide), falling back to project when the agent has no global file.
+  const pick = (a) => {
+    if (scope === 'project') return a.project ? { scope: 'project', t: a.project } : null;
+    if (scope === 'global') return a.global ? { scope: 'global', t: a.global } : null;
+    if (a.global) return { scope: 'global', t: a.global };
+    if (a.project) return { scope: 'project', t: a.project };
+    return null;
+  };
+
+  const wantAll = args.all === true || String(args.target || '').toLowerCase() === 'all';
+
+  // No target → show the matrix for THIS platform.
+  if (!wantAll && (args.list === true || !args.target)) {
+    printJson({
+      platform: process.platform,
+      agents: reg.map((a) => ({
+        agent: a.id, label: a.label,
+        global: a.global ? a.global.file : null,
+        project: a.project ? a.project.file : null,
+        note: a.note,
+      })),
+      usage: 'rly install --target <agent>[,<agent>] [--scope global|project] [--print] | rly install --all',
+    });
+    return 0;
+  }
+
+  // Resolve the set of {agent, scope, target} to act on.
+  let chosen;
+  if (wantAll) {
+    chosen = reg
+      .filter((a) => { try { return fs.existsSync(a.detect); } catch { return false; } })
+      .map((a) => ({ a, ...(pick(a) || {}) }))
+      .filter((x) => x.t);
+    if (!chosen.length) {
+      throw new CliError('no known agents detected on this machine (no ~/.claude, ~/.codex, ~/.cursor, ~/.kiro, …). Use --target <agent>.', 4);
+    }
+  } else {
+    const ids = String(args.target).split(',').map((s) => s.trim()).filter(Boolean);
+    chosen = [];
+    for (const id of ids) {
+      const a = byId[id];
+      if (!a) throw new CliError(`unknown agent "${id}". Run \`rly install --list\` to see supported agents.`, 4);
+      const p = pick(a);
+      if (!p) throw new CliError(`${a.label} has no ${scope || 'installable'} instruction file${a.note ? ` — ${a.note}` : ''}. Try \`--scope project\`.`, 4);
+      chosen.push({ a, ...p });
+    }
+  }
+
+  // --print: emit content + resolved path for manual copy/paste; no writes.
+  if (args.print === true) {
+    for (const { a, t } of chosen) {
+      const content = t.style === 'shared' ? `${RELAY_BEGIN}\n${SKILL_RULES}\n${RELAY_END}` : renderInstruction(t.style);
+      process.stdout.write(`# ${a.label}\n# → ${t.file}\n\n${content}\n\n`);
+    }
+    return 0;
+  }
+
+  const installed = chosen.map(({ a, scope: sc, t }) => ({
+    agent: a.id, scope: sc, file: t.file, action: writeInstruction(t),
+  }));
+  printJson({ installed, note: 'reload/re-open your agent (or re-list its rules) if it does not pick this up immediately' });
+  return 0;
+}
+
 function cmdAgent() {
   console.log(fs.readFileSync(path.join(PKG_ROOT, 'docs', 'AGENT.md'), 'utf8'));
   return 0;
@@ -863,7 +1058,9 @@ async function cmdUpgrade(args) {
 
   if (wantCli) {
     process.stderr.write(`\nUpgrading ${PKG_NAME} → latest  (npm install -g ${PKG_NAME}@latest)\n`);
-    const r = spawnSync('npm', ['install', '-g', `${PKG_NAME}@latest`], { stdio: 'inherit' });
+    // shell:true so Windows resolves `npm` → `npm.cmd` (same reason the skill /
+    // version spawns below use it); the package name has no shell metacharacters.
+    const r = spawnSync('npm', ['install', '-g', `${PKG_NAME}@latest`], { stdio: 'inherit', shell: true });
     if (r.error || r.status !== 0) {
       throw new CliError(
         `npm install failed${r.error ? ` (${r.error.message})` : ` (exit ${r.status})`}. ` +
@@ -954,6 +1151,9 @@ USAGE
   rly agent                           FULL GUIDE for AI agents (spec format, blocks, sizing, patterns)
   rly skill [install|rules|path]      bundled universal agent skill (Claude Code, Codex, …)
                                       \`rly skill rules >> CLAUDE.md\` adds always-read usage rules
+  rly install --target <agent>        inject relay's rules into an agent's instruction file
+                                      claude codex cursor copilot kiro windsurf cline gemini opencode droid agents
+                                      --scope global|project · --print (copy/paste) · --all · --list (no flags)
   rly upgrade                         install the latest CLI globally + refresh the skill in one step
                                       --stop/--force handle running boards · --dry-run · --cli-only/--skill-only
 
@@ -1018,6 +1218,8 @@ export async function main(argv) {
         return cmdRm(parseArgs(rest));
       case 'skill':
         return cmdSkill(rest);
+      case 'install':
+        return cmdInstall(parseArgs(rest));
       case 'upgrade':
       case 'self-update':
         return await cmdUpgrade(parseArgs(rest));