Skip to content

Commit a5a42e5

Browse files
docs(site): .js examples, separate the two paths, trim copy
- use .js (not .mjs) in all examples (run commands, runtime:process, imports) - clearly separate ES Runtime's two paths: the embeddable library is deny-by-default; the esrun CLI grants all capabilities. Never attribute deny-by-default to esrun. Reworded security page (two-path list), comparison bullet, docs/api overviews - trim: drop the Capabilities section + redundant cards from the API overview, the CLI "Capabilities" note, and the runtime:process preamble paragraph
1 parent 88bae2b commit a5a42e5

7 files changed

Lines changed: 45 additions & 107 deletions

File tree

site/app/api/cli/page.jsx

Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@ esrun -h, --help Show this help
88
esrun -v, --version Show the version`;
99

1010
const RUN = `# Run a module file
11-
esrun app.mjs
11+
esrun app.js
1212
1313
# Inline snippet (top-level await works)
1414
esrun -e "console.log(await Promise.resolve(42))"
1515
1616
# Pass arguments through to the script (read via runtime:process)
17-
esrun app.mjs build --watch
17+
esrun app.js build --watch
1818
1919
# Stop a runaway script after 500ms
20-
esrun -t 500 app.mjs`;
20+
esrun -t 500 app.js`;
2121

2222
const options = [
2323
{
@@ -90,17 +90,6 @@ export default function CliDoc() {
9090
</a>
9191
. The runtime binary and the script path are excluded.
9292
</div>
93-
94-
<div className="mt-4 rounded-xl border border-zinc-200 bg-zinc-50 p-5 text-sm leading-relaxed text-zinc-600">
95-
<strong className="text-zinc-900">Capabilities.</strong> The standalone
96-
CLI grants the host capabilities its features need so scripts “just run.”
97-
The deny-by-default model is what an <em>embedder</em> of the library
98-
controls — see the{" "}
99-
<a href="/api" className="font-medium text-brand-600 hover:text-brand-700">
100-
API overview
101-
</a>
102-
.
103-
</div>
10493
</ApiShell>
10594
);
10695
}

site/app/api/page.jsx

Lines changed: 3 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,6 @@ import CodeBlock from "../../components/CodeBlock.jsx";
33

44
const IMPORT = `import { env, args } from "runtime:process";`;
55

6-
const capabilities = [
7-
{ cap: "Env", grants: "Environment, arguments, cwd, platform — backs runtime:process." },
8-
{ cap: "FileRead", grants: "Read files within the configured root jail." },
9-
{ cap: "FileWrite", grants: "Write files within the configured root jail." },
10-
{ cap: "Net", grants: "Open outbound network connections." },
11-
{ cap: "HrTime", grants: "Access high-resolution timing." },
12-
];
13-
146
const modules = [
157
{ name: "runtime:process", status: "Available", cap: "Env", href: "/api/process" },
168
{ name: "runtime:path", status: "Planned", cap: "—", href: null },
@@ -27,8 +19,9 @@ export default function ApiOverview() {
2719
Overview
2820
</h1>
2921
<p className="mt-4 text-lg leading-relaxed text-zinc-600">
30-
ES Runtime is ESM-only, and its embeddable library is deny-by-default.
31-
Host functionality is exposed as ES modules under the{" "}
22+
ES Runtime is ESM-only; the embeddable library is deny-by-default (the
23+
esrun CLI grants all capabilities). Host functionality is exposed as ES
24+
modules under the{" "}
3225
<code className="rounded bg-zinc-100 px-1.5 py-0.5 font-mono text-[0.9em]">
3326
runtime:
3427
</code>{" "}
@@ -92,58 +85,6 @@ export default function ApiOverview() {
9285
</tbody>
9386
</table>
9487
</div>
95-
96-
<h2 className="mt-12 text-xl font-semibold text-zinc-900">Capabilities</h2>
97-
<p className="mt-3 text-zinc-600">
98-
A fresh runtime can compute but cannot reach the host until the embedder
99-
grants the relevant capability. The check lives on the native op, so it
100-
cannot be bypassed by reaching a different module path.
101-
</p>
102-
<div className="mt-5 overflow-hidden rounded-xl border border-zinc-200">
103-
<table className="w-full text-left text-sm">
104-
<thead className="bg-zinc-50 text-xs uppercase tracking-wider text-zinc-500">
105-
<tr>
106-
<th className="px-4 py-3 font-semibold">Capability</th>
107-
<th className="px-4 py-3 font-semibold">Grants</th>
108-
</tr>
109-
</thead>
110-
<tbody className="divide-y divide-zinc-100">
111-
{capabilities.map((c) => (
112-
<tr>
113-
<td className="px-4 py-3 font-mono font-medium text-zinc-900">
114-
{c.cap}
115-
</td>
116-
<td className="px-4 py-3 text-zinc-600">{c.grants}</td>
117-
</tr>
118-
))}
119-
</tbody>
120-
</table>
121-
</div>
122-
123-
<div className="mt-10 grid gap-4 sm:grid-cols-2">
124-
<a
125-
href="/api/cli"
126-
className="flex flex-col rounded-xl border border-zinc-200 p-5 transition-shadow hover:shadow-sm"
127-
>
128-
<span className="font-mono font-semibold text-zinc-900">
129-
esrun CLI →
130-
</span>
131-
<span className="mt-1 text-sm text-zinc-600">
132-
Command-line options: run a file, -e, --timeout, --help, --version.
133-
</span>
134-
</a>
135-
<a
136-
href="/api/process"
137-
className="flex flex-col rounded-xl border border-zinc-200 p-5 transition-shadow hover:shadow-sm"
138-
>
139-
<span className="font-mono font-semibold text-zinc-900">
140-
runtime:process →
141-
</span>
142-
<span className="mt-1 text-sm text-zinc-600">
143-
Environment, arguments, working directory, platform, and exit.
144-
</span>
145-
</a>
146-
</div>
14788
</ApiShell>
14889
);
14990
}

site/app/api/process/page.jsx

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ console.log(env.HOME); // read
1212
env.FEATURE_FLAG = "on"; // write (in-process only)
1313
delete env.SECRET; // delete (in-process only)`;
1414

15-
const ARGS_EX = `// esrun app.mjs build --watch
15+
const ARGS_EX = `// esrun app.js build --watch
1616
import { args } from "runtime:process";
1717
1818
console.log(args); // ["build", "--watch"]`;
@@ -79,13 +79,6 @@ export default function ProcessDoc() {
7979
</span>
8080
</div>
8181

82-
<p className="mt-8 text-zinc-600">
83-
Every member requires the <strong>Env</strong> capability; the check
84-
lives on the host op. Values are snapshotted when the module is
85-
evaluated, and the module is loaded on demand — importing it adds no cost
86-
to startup if you never use it.
87-
</p>
88-
8982
<h2 className="mt-12 text-xl font-semibold text-zinc-900">Import</h2>
9083
<div className="mt-4">
9184
<CodeBlock code={IMPORT} title="runtime:process" lang="js" />
@@ -114,21 +107,21 @@ export default function ProcessDoc() {
114107
env — reading and writing
115108
</h2>
116109
<div className="mt-4">
117-
<CodeBlock code={ENV_EX} title="env.mjs" lang="js" />
110+
<CodeBlock code={ENV_EX} title="env.js" lang="js" />
118111
</div>
119112

120113
<h2 className="mt-12 text-xl font-semibold text-zinc-900">
121114
args — program arguments
122115
</h2>
123116
<div className="mt-4">
124-
<CodeBlock code={ARGS_EX} title="args.mjs" lang="js" />
117+
<CodeBlock code={ARGS_EX} title="args.js" lang="js" />
125118
</div>
126119

127120
<h2 className="mt-12 text-xl font-semibold text-zinc-900">
128121
exit — stopping the run
129122
</h2>
130123
<div className="mt-4">
131-
<CodeBlock code={EXIT_EX} title="exit.mjs" lang="js" />
124+
<CodeBlock code={EXIT_EX} title="exit.js" lang="js" />
132125
</div>
133126

134127
<div className="mt-12 rounded-xl border border-zinc-200 bg-zinc-50 p-5 text-sm text-zinc-600">

site/app/docs/comparison/page.jsx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,8 @@ export default function ComparisonDoc() {
116116
File access — including module resolution — is confined to a project
117117
root that can't be escaped, even via symlink, in both the library and
118118
the CLI. Deno gates host access with CLI permission flags and Node.js
119-
has an experimental permission model; esrun's CLI grants all
120-
capabilities, while its embeddable library is deny-by-default.
119+
has an experimental permission model; the esrun CLI grants all
120+
capabilities, while the embeddable library is deny-by-default.
121121
</span>
122122
</li>
123123
<li className="flex gap-3">

site/app/docs/modules/page.jsx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@ import DocsShell from "../../../components/DocsShell.jsx";
22
import CodeBlock from "../../../components/CodeBlock.jsx";
33

44
const STATIC = `// Relative and bare specifiers both work.
5-
import { greet } from "./greet.mjs";
5+
import { greet } from "./greet.js";
66
import greeter from "greeter"; // from node_modules (ESM)
77
88
export const message = greet("world");`;
99

1010
const DYNAMIC = `// Dynamic import() is fully supported, including top-level await.
11-
const { default: plugin } = await import("./plugins/auth.mjs");
11+
const { default: plugin } = await import("./plugins/auth.js");
1212
await plugin.init();`;
1313

1414
const BUILTIN = `// Host functionality is imported under the runtime: scheme.
@@ -45,12 +45,12 @@ export default function ModulesDoc() {
4545

4646
<h2 className="mt-12 text-xl font-semibold text-zinc-900">Static imports</h2>
4747
<div className="mt-4">
48-
<CodeBlock code={STATIC} title="app.mjs" lang="js" />
48+
<CodeBlock code={STATIC} title="app.js" lang="js" />
4949
</div>
5050

5151
<h2 className="mt-12 text-xl font-semibold text-zinc-900">Dynamic import</h2>
5252
<div className="mt-4">
53-
<CodeBlock code={DYNAMIC} title="app.mjs" lang="js" />
53+
<CodeBlock code={DYNAMIC} title="app.js" lang="js" />
5454
</div>
5555

5656
<h2 className="mt-12 text-xl font-semibold text-zinc-900">
@@ -79,7 +79,7 @@ export default function ModulesDoc() {
7979
host dependency explicit and statically visible in the source.
8080
</p>
8181
<div className="mt-4">
82-
<CodeBlock code={BUILTIN} title="app.mjs" lang="js" />
82+
<CodeBlock code={BUILTIN} title="app.js" lang="js" />
8383
</div>
8484
<p className="mt-4 text-zinc-600">
8585
Each built-in module is backed by host ops that carry the capability

site/app/docs/page.jsx

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ import InstallBox from "../../components/InstallBox.jsx";
55
const GITHUB = "https://github.com/Open-Tech-Foundation/ES-Runtime";
66

77
const RUN = `# Run a module file
8-
esrun app.mjs
8+
esrun app.js
99
1010
# Evaluate an inline snippet (top-level await is supported)
1111
esrun -e "console.log(await Promise.resolve(42))"
1212
1313
# Pass arguments through to the script
14-
esrun app.mjs --name Ada`;
14+
esrun app.js --name Ada`;
1515

1616
export default function DocsOverview() {
1717
return (
@@ -21,18 +21,17 @@ export default function DocsOverview() {
2121
Overview
2222
</h1>
2323
<p className="mt-4 text-lg leading-relaxed text-zinc-600">
24-
esrun is a secure, standards-based JavaScript runtime for the server,
25-
built on V8 in Rust. It runs standard ES Modules with a sandboxed module
26-
system; its embeddable library is deny-by-default, granting host
27-
capabilities only when the host asks.
24+
ES Runtime is a secure, standards-based JavaScript runtime for the
25+
server, built on V8 in Rust. It runs standard ES Modules with a
26+
sandboxed module system.
2827
</p>
2928

3029
<div className="mt-6 rounded-xl border border-brand-200 bg-brand-50 p-5 leading-relaxed text-brand-900">
3130
Ships in two shapes from one core: an{" "}
32-
<strong>embeddable library</strong> and a{" "}
31+
<strong>embeddable library</strong>, which is deny-by-default, and the{" "}
3332
<strong>standalone CLI</strong> (
3433
<code className="rounded bg-white/70 px-1.5 py-0.5 text-[13px]">esrun</code>
35-
).
34+
), which grants all capabilities.
3635
</div>
3736

3837
<p className="mt-4 text-zinc-600">

site/app/docs/security/page.jsx

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,28 @@ export default function SecurityDoc() {
1616
Security model
1717
</h1>
1818
<p className="mt-4 text-lg leading-relaxed text-zinc-600">
19-
esrun's <strong>embeddable library</strong> is deny-by-default: a runtime
20-
the host creates can compute, but cannot reach the host environment, the
21-
filesystem, or the network until the host grants a capability for it. The
22-
standalone <code className="font-mono">esrun</code> CLI grants all
23-
capabilities, so scripts run unrestricted.
19+
ES Runtime ships in two forms, and they differ on what code can reach by
20+
default:
2421
</p>
22+
<ul className="mt-4 space-y-2 text-zinc-600">
23+
<li className="flex gap-3">
24+
<span className="mt-2 h-1.5 w-1.5 shrink-0 rounded-full bg-brand-500" />
25+
<span>
26+
<strong className="text-zinc-900">Embeddable library — deny-by-default.</strong>{" "}
27+
A runtime the host creates can compute, but cannot reach the host
28+
environment, filesystem, or network until the host grants a
29+
capability for it.
30+
</span>
31+
</li>
32+
<li className="flex gap-3">
33+
<span className="mt-2 h-1.5 w-1.5 shrink-0 rounded-full bg-brand-500" />
34+
<span>
35+
<strong className="text-zinc-900">The <code className="font-mono">esrun</code> CLI — unrestricted.</strong>{" "}
36+
The standalone binary grants all capabilities so scripts run without
37+
setup. It is not deny-by-default.
38+
</span>
39+
</li>
40+
</ul>
2541

2642
<h2 className="mt-12 text-xl font-semibold text-zinc-900">Capabilities</h2>
2743
<p className="mt-3 text-zinc-600">

0 commit comments

Comments
 (0)