Replace the sequence-first layout with a short explanation and one worked example. Move the sequence diagram under "What dev.site sees". Show example output lines in muted text.
- commit
- 2222e3b006dfc9107791d147eb93a8571933bf41
- parent
- 8976c4f79ee8af6db9269326e51b1225ec1237cf
- author
- Dami <dami.etoile@gmail.com>
| M | web/ | 2 | +- |
| M | web/ | 6 | +- |
| M | web/ | 111 | ++++++++++++++---------------- |
| M | web/ | 10 | ++- |
@@ -39,7 +39,7 @@ test('the signed-out home uses a font-independent wordmark', async ({ page }) =>
3939 4040 await page.goto('https://dev.site.test/');4141 42- await expect(page.getByRole('heading', { name: 'dev.site' })).toBeVisible();42+ await expect(page.getByRole('heading', { name: 'dev.site', exact: true })).toBeVisible();4343 await expect(page.locator('.home-wordmark')).toBeVisible();4444 await expect(page.locator('.home-wordmark path')).toHaveCount(1);4545 });@@ -14,6 +14,7 @@ function highlightCliExamples(container: Element) {
1414 1515 const highlighted = document.createDocumentFragment();1616 let wordIndex = 0;17+ let output = false;1718 source.split(/(\s+)/).forEach((token) => {1819 if (!token || /^\s+$/.test(token)) {1920 highlighted.append(token);@@ -21,8 +22,11 @@ function highlightCliExamples(container: Element) {
2122 return;2223 }2324 25+ // A line that starts with # is example output, not part of the command.26+ if (wordIndex === 0) output = token.startsWith('#');2427 const span = document.createElement('span');25- if (wordIndex === 0 && token === 'devsite') span.className = 'command-executable';28+ if (output) span.className = 'command-output';29+ else if (wordIndex === 0 && token === 'devsite') span.className = 'command-executable';2630 else if (wordIndex <= 2 && CLI_VERBS.has(token)) span.className = 'command-verb';2731 else if (token.startsWith('--')) span.className = 'command-option';2832 else if (/^(?:dmt|dsp|dss|dst)_/.test(token)) span.className = 'command-secret';@@ -36,7 +36,7 @@
3636 </header>3737 3838 <template id="home-template">39- <article>39+ <article class="home-intro">4040 <hgroup>4141 <h1 aria-label="dev.site">4242 <svg class="home-wordmark" viewBox="0 0 64.8 10" aria-hidden="true"@@ -44,10 +44,42 @@
4444 <path d="M4.8 0H6V1H4.8ZM44.4 0H45.6V1H44.4ZM4.8 1H6V2H4.8ZM52.8 1H54V2H52.8ZM4.8 2H6V3H4.8ZM52.8 2H54V3H52.8ZM1.2 3H6V4H1.2ZM9.6 3H13.2V4H9.6ZM16.8 3H18V4H16.8ZM21.6 3H22.8V4H21.6ZM34.8 3H38.4V4H34.8ZM42 3H45.6V4H42ZM50.4 3H56.4V4H50.4ZM60 3H63.6V4H60ZM0 4H2.4V5H0ZM3.6 4H6V5H3.6ZM8.4 4H10.8V5H8.4ZM13.2 4H14.4V5H13.2ZM16.8 4H18V5H16.8ZM21.6 4H22.8V5H21.6ZM33.6 4H34.8V5H33.6ZM38.4 4H39.6V5H38.4ZM44.4 4H45.6V5H44.4ZM52.8 4H54V5H52.8ZM58.8 4H61.2V5H58.8ZM63.6 4H64.8V5H63.6ZM0 5H1.2V6H0ZM4.8 5H6V6H4.8ZM8.4 5H9.6V6H8.4ZM13.2 5H14.4V6H13.2ZM18 5H19.2V6H18ZM20.4 5H21.6V6H20.4ZM33.6 5H34.8V6H33.6ZM44.4 5H45.6V6H44.4ZM52.8 5H54V6H52.8ZM58.8 5H60V6H58.8ZM63.6 5H64.8V6H63.6ZM0 6H1.2V7H0ZM4.8 6H6V7H4.8ZM8.4 6H14.4V7H8.4ZM18 6H19.2V7H18ZM20.4 6H21.6V7H20.4ZM34.8 6H38.4V7H34.8ZM44.4 6H45.6V7H44.4ZM52.8 6H54V7H52.8ZM58.8 6H64.8V7H58.8ZM0 7H1.2V8H0ZM4.8 7H6V8H4.8ZM8.4 7H9.6V8H8.4ZM18 7H21.6V8H18ZM38.4 7H39.6V8H38.4ZM44.4 7H45.6V8H44.4ZM52.8 7H54V8H52.8ZM58.8 7H60V8H58.8ZM0 8H2.4V9H0ZM3.6 8H6V9H3.6ZM8.4 8H10.8V9H8.4ZM13.2 8H14.4V9H13.2ZM19.2 8H20.4V9H19.2ZM27.6 8H28.8V9H27.6ZM33.6 8H34.8V9H33.6ZM38.4 8H39.6V9H38.4ZM44.4 8H45.6V9H44.4ZM52.8 8H54V9H52.8ZM58.8 8H61.2V9H58.8ZM63.6 8H64.8V9H63.6ZM1.2 9H6V10H1.2ZM9.6 9H13.2V10H9.6ZM19.2 9H20.4V10H19.2ZM27.6 9H28.8V10H27.6ZM34.8 9H38.4V10H34.8ZM42 9H48V10H42ZM54 9H56.4V10H54ZM60 9H63.6V10H60Z"></path>4545 </svg>4646 </h1>47- <p>links and services across all of your development sites</p>47+ <p>Links and private services on one profile page.</p>4848 </hgroup>49+ <p>dev.site gives you a page at <code>dev.site/@you</code>. It holds links and services.50+ A service is a TCP port on one of your machines, for example a database or a development51+ server. You choose who can see and use each item.</p>52+ </article>53+54+ <section aria-labelledby="example-title">55+ <h2 id="example-title">An example</h2>56+ <p>You run Postgres on port 5432 on your laptop. A teammate needs to query it. On your57+ laptop, name the port and keep the daemon running:</p>58+ <pre><code>devsite service host 5432 --name postgres59+devsite daemon run</code></pre>60+ <p>Share <code>postgres</code> with your teammate on the dashboard. They accept the share,61+ get a ticket from your profile, and run:</p>62+ <pre><code>devsite connect dst_***63+# connected to postgres64+# listening on 127.0.0.1:43127</code></pre>65+ <p>Their <code>psql</code> now connects to <code>127.0.0.1:43127</code>. The data goes66+ from their machine to yours. Your laptop does not open a port to the internet.</p>67+ <p>Links work in the same way, without the daemon:</p>68+ <pre><code>devsite link set --name docs --url https://docs.example.com --public</code></pre>69+ </section>70+71+ <section aria-labelledby="install-title">72+ <h2 id="install-title">Install</h2>73+ <div data-install-control></div>74+ <p>Then sign in, create a machine ticket on the dashboard, and use it on this machine:</p>75+ <pre><code>devsite login dmt_***</code></pre>76+ </section>77+78+ <article aria-labelledby="sees-title">79+ <h2 id="sees-title">What dev.site sees</h2>80+ <p>dev.site handles sign-in, profiles, shares, and permission for each connection. It81+ does not carry your service data. It does not know your local port numbers.</p>4982 <figure class="sequence">50- <figcaption>authorization only - no service bytes</figcaption>5183 <header aria-hidden="true">5284 <strong>host cli</strong>5385 <strong>dev.site</strong>@@ -66,69 +98,32 @@
6698 </ol>6799 </div>68100 </figure>101+ <nav aria-label="Security concept guides">102+ <ul>103+ <li><a href="/concepts.html#tickets">Tickets</a></li>104+ <li><a href="/concepts.html#keys">Keys</a></li>105+ <li><a href="/concepts.html#protocol">ALPN</a></li>106+ </ul>107+ </nav>69108 </article>70109 71- <section aria-labelledby="install-title">72- <h2 id="install-title">Install</h2>73- <div data-install-control></div>74- </section>75-76- <hr>77-78110 <details>79- <summary>Overview</summary>80- <p>Store useful URLs, shared services, and temporary access</p>81- <article>82- <h3>Machine Enrollment</h3>83- <pre><code>devsite login dmt_***</code></pre>84- <blockquote>A single-use ticket creates a revocable, identity-bound machine credential</blockquote>85- </article>86- <article>87- <h3>Add Links to your site</h3>88- <pre><code>devsite link set --name docs --url https://docs.example.com --public</code></pre>89- <blockquote>List a public, private, shared URLs on your page</blockquote>90- </article>91- <article>92- <h3>Share your Services</h3>93- <pre><code>devsite service host 5432 --name postgres</code></pre>94- <blockquote>95- <p>Access any local TCP port. never publicly accessible</p>96- <p>Service is accessed anywhere with a single use ticket.</p>97- </blockquote>98- <pre><code>devsite connect dst_***</code></pre>99- </article>100- <article>101- <h3>Delegate Granular Access</h3>102- <blockquote><p>A sandboxed agent can request a service by keyword. The request is matched to an accessible service, and a scoped grant is presented for approval.</p>103- <p>The requester receives only a short-lived grant bound to the selected104- service and its temporary endpoint.</p></blockquote>105- <pre><code>devsite access request postgres --request request.json --key requester.key</code></pre>106- <blockquote>Resolution is limited to services available to the approving account. Grants107- are short-lived and revocable.</blockquote>108- <pre><code>devsite access resolve postgres111+ <summary>Give an agent limited access</summary>112+ <p>A sandboxed agent can ask for a service by name. You see the request and approve it.113+ The agent then gets a short-lived grant for that one service. You can revoke it.</p>114+ <pre><code>devsite access request postgres --request request.json --key requester.key</code></pre>115+ <p>On your machine, find the service, check the plan, and approve it.</p>116+ <pre><code>devsite access resolve postgres109117 devsite access grant --request request.json --plan110118 devsite access grant --request request.json --approved-plan dsp_***</code></pre>111- <blockquote>The requester opens an on-demand, endpoint-bound connection to the selected service.</blockquote>112- <pre><code>devsite access connect dss_*** --key requester.key</code></pre>113- </article>114- <article>115- <h3>Persist the Daemon</h3>116- <pre><code>devsite daemon run</code></pre>117- <blockquote>autorun it with Homebrew services or systemd to keep services available for118- on-demand connections</blockquote>119- </article>119+ <p>The agent connects with its grant.</p>120+ <pre><code>devsite access connect dss_*** --key requester.key</code></pre>120121 </details>121122 122123 <details>123- <summary>Important Concepts</summary>124- <p>Tickets, keys, and the ALPN tell the story of how it works</p>125- <nav aria-label="Security concept guides">126- <ul>127- <li><a href="/concepts.html#tickets">Tickets</a></li>128- <li><a href="/concepts.html#keys">Keys</a></li>129- <li><a href="/concepts.html#protocol">ALPN</a></li>130- </ul>131- </nav>124+ <summary>Run the daemon at startup</summary>125+ <p>Start <code>devsite daemon run</code> with Homebrew services or systemd. Your services126+ then stay available after a restart.</p>132127 </details>133128 </template>134129 @@ -299,7 +299,7 @@ details:not(.dropdown)[open] > summary::after {
299299 }300300 301301 /* The sequence diagram is the signed-out page's one bespoke element. */302-main > article:has(> .sequence) .home-wordmark {302+.home-intro .home-wordmark {303303 display: block;304304 width: min(100%, 35.64rem);305305 height: auto;@@ -307,12 +307,16 @@ main > article:has(> .sequence) .home-wordmark {
307307 shape-rendering: crispEdges;308308 }309309 310-main > article:has(> .sequence) h1 {310+.home-intro h1 {311311 margin-bottom: var(--pico-typography-spacing-vertical);312312 }313313 314314 .sequence {315- margin: var(--pico-block-spacing-vertical) 0 0;315+ margin: var(--pico-block-spacing-vertical) 0;316+}317+318+.command-output {319+ color: var(--pico-muted-color);316320 }317321 .sequence figcaption {318322 color: var(--pico-muted-color);