realontext 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,12 +4,33 @@ Code search for coding agents, over the directory you are in: tree-sitter
4
4
  chunks ranked by BM25 and, when you are logged in, narrowed down by the jev
5
5
  model through the realontext Relay.
6
6
 
7
+ ## Installing
8
+
9
+ ```bash
10
+ npm install -g realontext
11
+ ```
12
+
13
+ ## The menu
14
+
15
+ Run `realontext` with no command, in the repository's root: connect agents,
16
+ log in, and see your plan, credits left and last queries.
17
+
7
18
  ## As an MCP server
8
19
 
9
- In the repository's MCP configuration:
20
+ In the repository's root, connect your agent:
21
+
22
+ ```bash
23
+ realontext setup # pick the agents in the menu
24
+ realontext setup claude codex # or name them: claude, codex, gemini, cursor, vscode, opencode
25
+ ```
26
+
27
+ It runs the agent's own `mcp add` (Claude Code, Codex, Gemini CLI) or writes
28
+ the entry into the repository's config (`.cursor/mcp.json`, `.vscode/mcp.json`,
29
+ `opencode.json`), replacing any earlier realontext entry. For any other MCP
30
+ client:
10
31
 
11
32
  ```jsonc
12
- { "realontext": { "command": "npx", "args": ["-y", "realontext", "mcp"] } }
33
+ { "realontext": { "command": "realontext", "args": ["mcp"] } }
13
34
  ```
14
35
 
15
36
  ## Logging in
@@ -19,8 +40,8 @@ Log in once; the Token is kept in `~/.config/realontext/config.toml`
19
40
  repository uses it:
20
41
 
21
42
  ```bash
22
- npx -y realontext login # in the browser
23
- npx -y realontext login --paste # when the browser is on another machine
43
+ realontext login # in the browser
44
+ realontext login --paste # when the browser is on another machine
24
45
  ```
25
46
 
26
47
  With a Token, each query asks jev four rounds of questions (which files, which
@@ -33,8 +54,8 @@ set to an empty string, it turns jev off for that process.
33
54
  ## From the shell
34
55
 
35
56
  ```bash
36
- echo "why does loading yaml crash" | npx realontext query --k 20
37
- npx realontext symbols
57
+ echo "why does loading yaml crash" | realontext query --k 20
58
+ realontext symbols
38
59
  ```
39
60
 
40
61
  Builds: macOS on Apple Silicon (13 and later), x64 Linux and x64 Windows.
package/bin/realontext.js CHANGED
@@ -1,43 +1,36 @@
1
1
  #!/usr/bin/env node
2
- // The `realontext` command npm installs: finds the binary of the platform
3
- // package npm picked through optionalDependencies and runs it with this
4
- // process's arguments, stdio and exit status (D39).
2
+ // The `realontext` command npm installs: runs the binary of this platform with
3
+ // this process's arguments, stdio and exit status (D39). What is written here
4
+ // instead is what Node does better: `setup` edits agents' configs (D74), and
5
+ // with no command, in a terminal, a menu of everything (D75).
5
6
  "use strict";
6
7
 
7
8
  const { spawnSync } = require("child_process");
8
9
 
9
- const packages = {
10
- "darwin arm64": "@realontext/darwin-arm64",
11
- "linux x64": "@realontext/linux-x64",
12
- "win32 x64": "@realontext/win32-x64",
13
- };
10
+ const [command, ...rest] = process.argv.slice(2);
11
+ const terminal = process.stdin.isTTY && process.stdout.isTTY;
14
12
 
15
- const name = packages[`${process.platform} ${process.arch}`];
16
- if (!name) {
17
- console.error(
18
- `realontext: no build for ${process.platform}-${process.arch}; ` +
19
- `there are builds for ${Object.keys(packages).map((k) => k.replace(" ", "-")).join(", ")}`
20
- );
21
- process.exit(1);
13
+ if (terminal && (command === undefined || (command === "setup" && rest.length === 0))) {
14
+ import("../lib/tui.mjs")
15
+ .then((tui) => tui.default(command === "setup" ? "setup" : "home"))
16
+ .then((status) => process.exit(status));
17
+ } else if (command === "setup") {
18
+ process.exit(require("../lib/setup.js").setup(rest));
19
+ } else {
20
+ let path;
21
+ try {
22
+ path = require("../lib/binary.js")();
23
+ } catch (e) {
24
+ console.error(`realontext: ${e.message}`);
25
+ process.exit(1);
26
+ }
27
+ const run = spawnSync(path, process.argv.slice(2), { stdio: "inherit" });
28
+ if (run.error) {
29
+ console.error(`realontext: ${run.error.message}`);
30
+ process.exit(1);
31
+ }
32
+ if (run.signal) {
33
+ process.kill(process.pid, run.signal);
34
+ }
35
+ process.exit(run.status);
22
36
  }
23
-
24
- let binary;
25
- try {
26
- binary = require.resolve(`${name}/bin/realontext${process.platform === "win32" ? ".exe" : ""}`);
27
- } catch {
28
- console.error(
29
- `realontext: ${name} is not installed. It is an optional dependency of realontext; ` +
30
- `reinstall without --no-optional / --omit=optional.`
31
- );
32
- process.exit(1);
33
- }
34
-
35
- const run = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
36
- if (run.error) {
37
- console.error(`realontext: ${run.error.message}`);
38
- process.exit(1);
39
- }
40
- if (run.signal) {
41
- process.kill(process.pid, run.signal);
42
- }
43
- process.exit(run.status);
package/lib/binary.js ADDED
@@ -0,0 +1,27 @@
1
+ // The binary of the platform package npm picked through optionalDependencies
2
+ // (D39). Throws when there is none for this machine.
3
+ "use strict";
4
+
5
+ const packages = {
6
+ "darwin arm64": "@realontext/darwin-arm64",
7
+ "linux x64": "@realontext/linux-x64",
8
+ "win32 x64": "@realontext/win32-x64",
9
+ };
10
+
11
+ module.exports = function binary() {
12
+ const name = packages[`${process.platform} ${process.arch}`];
13
+ if (!name) {
14
+ throw new Error(
15
+ `no build for ${process.platform}-${process.arch}; ` +
16
+ `there are builds for ${Object.keys(packages).map((k) => k.replace(" ", "-")).join(", ")}`
17
+ );
18
+ }
19
+ try {
20
+ return require.resolve(`${name}/bin/realontext${process.platform === "win32" ? ".exe" : ""}`);
21
+ } catch {
22
+ throw new Error(
23
+ `${name} is not installed. It is an optional dependency of realontext; ` +
24
+ `reinstall without --no-optional / --omit=optional.`
25
+ );
26
+ }
27
+ };
package/lib/setup.js ADDED
@@ -0,0 +1,99 @@
1
+ // `realontext setup [agent...]`: connects agents to `realontext mcp` the way
2
+ // the console's quick start documents it, run from the repository root (D74).
3
+ // With no agent named, the menu in `tui.mjs` asks which. An agent with its
4
+ // own `mcp add` is asked through it; the others get the entry written into
5
+ // the repository's JSON config. Either way an existing realontext entry, such
6
+ // as an older `npx` one, is replaced.
7
+ "use strict";
8
+
9
+ const fs = require("fs");
10
+ const path = require("path");
11
+ const { spawnSync } = require("child_process");
12
+
13
+ const agents = {
14
+ claude: {
15
+ name: "Claude Code",
16
+ // `claude mcp add` refuses a name it already has in this scope.
17
+ clear: "claude mcp remove realontext -s local",
18
+ run: "claude mcp add realontext -- realontext mcp",
19
+ },
20
+ codex: {
21
+ name: "Codex",
22
+ run: "codex mcp add realontext -- realontext mcp",
23
+ },
24
+ gemini: {
25
+ name: "Gemini CLI",
26
+ run: "gemini mcp add realontext realontext mcp",
27
+ note: "Gemini CLI starts MCP servers only in trusted folders: trust this one when it asks.",
28
+ },
29
+ cursor: {
30
+ name: "Cursor",
31
+ file: ".cursor/mcp.json",
32
+ key: "mcpServers",
33
+ entry: { command: "realontext", args: ["mcp"] },
34
+ note: "Approve the server once: in the editor when it asks, or `cursor-agent mcp enable realontext`.",
35
+ },
36
+ vscode: {
37
+ name: "VS Code",
38
+ file: ".vscode/mcp.json",
39
+ key: "servers",
40
+ entry: { type: "stdio", command: "realontext", args: ["mcp"] },
41
+ },
42
+ opencode: {
43
+ name: "opencode",
44
+ file: "opencode.json",
45
+ key: "mcp",
46
+ entry: { type: "local", command: ["realontext", "mcp"] },
47
+ },
48
+ };
49
+
50
+ // Through a shell, so that npm's `.cmd` wrappers run on Windows too. Every
51
+ // word is a plain one: nothing to quote.
52
+ function sh(command, quiet) {
53
+ const run = spawnSync(command, { shell: true, stdio: quiet ? "ignore" : "inherit" });
54
+ if (run.error) throw run.error;
55
+ return run.status ?? 1;
56
+ }
57
+
58
+ function write(agent) {
59
+ let config = {};
60
+ if (fs.existsSync(agent.file)) {
61
+ try {
62
+ config = JSON.parse(fs.readFileSync(agent.file, "utf8"));
63
+ } catch (e) {
64
+ throw new Error(
65
+ `${agent.file} is not plain JSON (${e.message}); add this under "${agent.key}" by hand:\n` +
66
+ JSON.stringify({ realontext: agent.entry }, null, 2)
67
+ );
68
+ }
69
+ }
70
+ config[agent.key] = { ...config[agent.key], realontext: agent.entry };
71
+ fs.mkdirSync(path.dirname(agent.file), { recursive: true });
72
+ fs.writeFileSync(agent.file, JSON.stringify(config, null, 2) + "\n");
73
+ console.error(`realontext: wrote ${agent.file}`);
74
+ return 0;
75
+ }
76
+
77
+ function connect(agent) {
78
+ let status;
79
+ try {
80
+ if (agent.clear) sh(agent.clear, true);
81
+ status = agent.file ? write(agent) : sh(agent.run, false);
82
+ } catch (e) {
83
+ console.error(`realontext: ${e.message}`);
84
+ return 1;
85
+ }
86
+ if (status === 0 && agent.note) console.error(agent.note);
87
+ return status;
88
+ }
89
+
90
+ // Every agent named gets its turn; one failing does not stop the rest.
91
+ function setup(keys) {
92
+ if (!keys.length || keys.some((k) => !agents[k])) {
93
+ console.error(`usage: realontext setup [agent...], in the repository's root\nagents: ${Object.keys(agents).join(", ")}`);
94
+ return 2;
95
+ }
96
+ return keys.map((k) => connect(agents[k])).some((status) => status !== 0) ? 1 : 0;
97
+ }
98
+
99
+ module.exports = { agents, setup };
package/lib/tui.mjs ADDED
@@ -0,0 +1,178 @@
1
+ // What `realontext` opens with no command, in a terminal (D75): the account
2
+ // behind the Token, connecting agents, logging in. The Relay is asked through
3
+ // the binary (`usage`, `login`), agents are connected through `setup.js`.
4
+ //
5
+ // A screen that needs the terminal to itself (login waits on the browser or
6
+ // reads a pasted Token; an agent's own `mcp add` prints) closes the menu, runs,
7
+ // and the menu opens again below what it printed.
8
+ import { execFile, spawnSync } from "node:child_process";
9
+ import { createRequire } from "node:module";
10
+ import React, { useEffect, useState } from "react";
11
+ import { Box, Text, render, useApp, useInput } from "ink";
12
+
13
+ const require = createRequire(import.meta.url);
14
+ const { agents, setup } = require("./setup.js");
15
+ const binary = require("./binary.js");
16
+ const { version } = require("../package.json");
17
+ const h = React.createElement;
18
+
19
+ // `realontext usage`: {account, queries}, or {error} with what went wrong.
20
+ function usage() {
21
+ return new Promise((resolve) => {
22
+ execFile(binary(), ["usage"], (err, stdout, stderr) =>
23
+ resolve(err ? { error: stderr.trim().replace(/^realontext: /, "") || err.message } : JSON.parse(stdout))
24
+ );
25
+ }).catch((e) => ({ error: e.message }));
26
+ }
27
+
28
+ function run(args) {
29
+ try {
30
+ spawnSync(binary(), args, { stdio: "inherit" });
31
+ } catch (e) {
32
+ console.error(`realontext: ${e.message}`);
33
+ }
34
+ }
35
+
36
+ // Up and down move, enter picks, esc or q goes back. With `multiple`, space
37
+ // ticks, and enter picks the ticked items, or the one under the cursor when
38
+ // none is ticked. `onPick` gets the indices picked.
39
+ function List({ items, multiple, onPick, onBack }) {
40
+ const [at, setAt] = useState(0);
41
+ const [ticked, setTicked] = useState(() => new Set());
42
+ useInput((input, key) => {
43
+ if (key.upArrow || input === "k") setAt((at + items.length - 1) % items.length);
44
+ else if (key.downArrow || input === "j") setAt((at + 1) % items.length);
45
+ else if (input === " " && multiple) {
46
+ const next = new Set(ticked);
47
+ next.has(at) ? next.delete(at) : next.add(at);
48
+ setTicked(next);
49
+ } else if (key.return) onPick(ticked.size ? [...ticked].sort() : [at]);
50
+ else if (key.escape || input === "q") onBack();
51
+ });
52
+ return h(
53
+ Box,
54
+ { flexDirection: "column" },
55
+ items.map((label, i) =>
56
+ h(
57
+ Text,
58
+ { key: label, color: i === at ? "cyan" : undefined, bold: i === at },
59
+ `${i === at ? ">" : " "} ${multiple ? (ticked.has(i) ? "[x] " : "[ ] ") : ""}${label}`
60
+ )
61
+ )
62
+ );
63
+ }
64
+
65
+ function Account({ account }) {
66
+ if (!account) return h(Text, { dimColor: true }, "Checking the account...");
67
+ if (account.error) return h(Text, { color: "yellow" }, account.error);
68
+ const { email, plan, end_at, credit } = account.account;
69
+ const term = plan ? `${plan} plan${end_at ? ` until ${end_at.slice(0, 10)}` : ""}` : "no plan";
70
+ return h(Text, null, `${email} · ${term} · ${credit} credits left`);
71
+ }
72
+
73
+ // A screen, or a thing to run once the menu has closed; neither is quitting.
74
+ const HOME = [
75
+ { label: "Connect agents in this directory", screen: "setup" },
76
+ { label: "Usage", screen: "usage" },
77
+ { label: "Log in in the browser", then: () => run(["login"]) },
78
+ { label: "Log in with a pasted Token", then: () => run(["login", "--paste"]) },
79
+ { label: "Quit" },
80
+ ];
81
+
82
+ function Home({ go, done }) {
83
+ return h(List, {
84
+ items: HOME.map((item) => item.label),
85
+ onPick: ([i]) => (HOME[i].screen ? go(HOME[i].screen) : done(HOME[i].then)),
86
+ onBack: () => done(),
87
+ });
88
+ }
89
+
90
+ function Setup({ go, done }) {
91
+ const keys = Object.keys(agents);
92
+ return h(
93
+ Box,
94
+ { flexDirection: "column" },
95
+ h(Text, { dimColor: true }, "space ticks, enter connects, esc goes back"),
96
+ h(List, {
97
+ items: keys.map((k) => agents[k].name),
98
+ multiple: true,
99
+ onPick: (picked) => done(() => setup(picked.map((i) => keys[i]))),
100
+ onBack: () => go("home"),
101
+ })
102
+ );
103
+ }
104
+
105
+ function Usage({ account, go }) {
106
+ useInput((input, key) => {
107
+ if (key.escape || key.return || input === "q") go("home");
108
+ });
109
+ const back = h(Text, { dimColor: true }, "esc goes back");
110
+ if (!account || account.error) return back;
111
+ const { plan, end_at, credit } = account.account;
112
+ const queries = account.queries.items;
113
+ return h(
114
+ Box,
115
+ { flexDirection: "column" },
116
+ h(Text, null, `Plan ${plan ?? "none"}${end_at ? `, until ${end_at} UTC` : ""}`),
117
+ h(Text, null, `Credits ${credit} left`),
118
+ h(Text, { bold: true }, `\n${"Last queries charged".padEnd(25)}seconds status`),
119
+ queries.length
120
+ ? queries.map((q) =>
121
+ h(Text, { key: q.id }, `${q.time} UTC ${(q.duration_ms / 1000).toFixed(1).padStart(7)} ${q.status}`)
122
+ )
123
+ : h(Text, { dimColor: true }, "none yet"),
124
+ back
125
+ );
126
+ }
127
+
128
+ const SCREENS = { home: Home, setup: Setup, usage: Usage };
129
+
130
+ function App({ start, onDone }) {
131
+ const { exit } = useApp();
132
+ const [screen, go] = useState(start);
133
+ const [account, setAccount] = useState(null);
134
+ useEffect(() => {
135
+ usage().then(setAccount);
136
+ }, []);
137
+ const done = (then) => {
138
+ onDone(then);
139
+ exit();
140
+ };
141
+ return h(
142
+ Box,
143
+ { flexDirection: "column", gap: 1 },
144
+ h(
145
+ Box,
146
+ { flexDirection: "column" },
147
+ h(Text, { bold: true }, `realontext ${version} `, h(Text, { dimColor: true }, process.cwd())),
148
+ h(Account, { account })
149
+ ),
150
+ h(SCREENS[screen], { account, go, done })
151
+ );
152
+ }
153
+
154
+ // Resolves to what to run once the menu has closed, or nothing to quit. The
155
+ // menu is wiped first: what runs prints where it was.
156
+ async function show(start) {
157
+ let then;
158
+ const app = render(
159
+ h(App, {
160
+ start,
161
+ onDone: (f) => {
162
+ then = f;
163
+ app.clear();
164
+ },
165
+ })
166
+ );
167
+ await app.waitUntilExit();
168
+ return then;
169
+ }
170
+
171
+ export default async function tui(start) {
172
+ for (let screen = start; ; screen = "home") {
173
+ const then = await show(screen);
174
+ if (!then) return 0;
175
+ then();
176
+ console.log();
177
+ }
178
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "realontext",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Code search for coding agents, over the directory you are in. CLI and MCP server.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {
@@ -12,14 +12,19 @@
12
12
  "realontext": "bin/realontext.js"
13
13
  },
14
14
  "files": [
15
- "bin/realontext.js"
15
+ "bin/realontext.js",
16
+ "lib/"
16
17
  ],
17
18
  "engines": {
18
19
  "node": ">=18"
19
20
  },
21
+ "dependencies": {
22
+ "ink": "^5.2.1",
23
+ "react": "^18.3.1"
24
+ },
20
25
  "optionalDependencies": {
21
- "@realontext/darwin-arm64": "0.2.0",
22
- "@realontext/linux-x64": "0.2.0",
23
- "@realontext/win32-x64": "0.2.0"
26
+ "@realontext/darwin-arm64": "0.4.0",
27
+ "@realontext/linux-x64": "0.4.0",
28
+ "@realontext/win32-x64": "0.4.0"
24
29
  }
25
30
  }