Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: add an unlinked browser demo for production testing (#4280)

Konstantin Goncharukd965d819f226
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 948986189..5dfb7963f 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -81,7 +81,7 @@ export default defineConfig({
sidebar,
}),
sitemap({
- filter: (page) => ![`${site}/404/`, `${site}/worktrunk/`].includes(page),
+ filter: (page) => ![`${site}/404/`, `${site}/worktrunk/`, `${site}/try-it/`].includes(page),
}),
sitemapCompatibility(),
],
diff --git a/docs/demos/demoshell/README.md b/docs/demos/demoshell/README.md
new file mode 100644
index 000000000..80c84e239
--- /dev/null
+++ b/docs/demos/demoshell/README.md
@@ -0,0 +1,27 @@
+# Try it demo
+
+The [Try it](https://worktrunk.dev/try-it/) page embeds a [Demoshell](https://demoshell.com) VM: Alpine Linux on an emulated arm64 CPU, running in the visitor's browser with `wt` installed. `docs/src/pages/try-it.astro` mounts it by its Demoshell reference.
+
+The VM's definition is kept here and entered into the Demoshell studio, where the VM is built and saved:
+
+| File | Studio field |
+|------|--------------|
+| `recipe.sh` | Base image script |
+| `after-load.sh` | Files → `/root/after-load.sh` |
+| `guide.json` | Guide: title, order, finish card, and steps |
+
+`guide.json` uses the field names Demoshell's embed API serves for a guide. Command steps tick when the visitor runs `pattern`, and `output_contains` must appear in its output, so check those strings against real output when changing the recipe or `wt`'s messages. The optional interactive picker uses a manual step: Demoshell does not detect completion when it leaves the terminal's alternate screen.
+
+Set **When a visitor opens the VM → Start an app** to `bash --rcfile /root/after-load.sh`. Demoshell's shell-prompt mode runs ash even if the recipe changes root's login shell. Starting bash explicitly loads Worktrunk's shell integration so switching and merging move the visitor's shell.
+
+To check the full recipe before a Studio build, run this from the repository root with Docker:
+
+```bash
+docker run --rm -it --platform linux/arm64 \
+ -v "$PWD/docs/demos/demoshell:/demo:ro" \
+ alpine:latest sh -ec 'sh -e /demo/recipe.sh; exec bash --rcfile /demo/after-load.sh'
+```
+
+In the container, run each command step's `pattern` from `guide.json`, then try the optional picker as described. Check that each command step's `output_contains` appears and that merging returns the shell to `/root/acme` with the updated price. This exercises the release download and Alpine shell setup as well as the guide commands; the Studio build and automatic guide completion still need checking in Demoshell.
+
+Demoshell rebuilds the VM when a Worktrunk release is published, so the recipe installs the latest release rather than a pinned version.
diff --git a/docs/demos/demoshell/after-load.sh b/docs/demos/demoshell/after-load.sh
new file mode 100644
index 000000000..100a494cd
--- /dev/null
+++ b/docs/demos/demoshell/after-load.sh
@@ -0,0 +1,5 @@
+# Bash rcfile for Demoshell's "Start an app" command; see README.md.
+. "$HOME/.bashrc"
+cd "$HOME/acme"
+clear
+echo "A git repository with two worktrees in flight. Follow the guide to the right."
diff --git a/docs/demos/demoshell/guide.json b/docs/demos/demoshell/guide.json
new file mode 100644
index 000000000..3a4efcce2
--- /dev/null
+++ b/docs/demos/demoshell/guide.json
@@ -0,0 +1,68 @@
+{
+ "title": "Take a change from a new worktree to main",
+ "order_mode": "fixed",
+ "cta_label": "Install Worktrunk",
+ "cta_url": "https://worktrunk.dev/#install",
+ "steps": [
+ {
+ "title": "See every worktree at once",
+ "body": "One row per worktree: docs is a commit ahead of main, and experiment has uncommitted changes (!). @ marks where you are.",
+ "kind": "command",
+ "match_mode": "exact",
+ "pattern": "wt list",
+ "output_contains": "Showing 3 worktrees",
+ "require_success": true,
+ "optional": false
+ },
+ {
+ "title": "Start a worktree for a new change",
+ "body": "--create makes the branch and its worktree together and moves your shell into it: one command in place of git worktree add plus a cd.",
+ "kind": "command",
+ "match_mode": "exact",
+ "pattern": "wt switch --create raise-price",
+ "output_contains": "Created branch",
+ "require_success": true,
+ "optional": false
+ },
+ {
+ "title": "Make the change",
+ "body": "Edit a file as you or an agent would. The other worktrees don't see it.",
+ "kind": "command",
+ "match_mode": "exact",
+ "pattern": "sed -i 's/19\\/month/24\\/month/' pricing.txt",
+ "output_contains": null,
+ "require_success": true,
+ "optional": false
+ },
+ {
+ "title": "See the change in the list",
+ "body": "raise-price now shows ! for uncommitted changes and +1 -1 for the lines changed.",
+ "kind": "command",
+ "match_mode": "exact",
+ "pattern": "wt list",
+ "output_contains": "Showing 4 worktrees",
+ "require_success": true,
+ "optional": false
+ },
+ {
+ "title": "Merge it into main",
+ "body": "No git commit needed: wt merge commits the change, rebases onto main if needed, fast-forwards main, removes the worktree and branch, and brings your shell back to main.",
+ "kind": "command",
+ "match_mode": "exact",
+ "pattern": "wt merge",
+ "output_contains": "Merged to",
+ "require_success": true,
+ "optional": false
+ },
+ {
+ "title": "Jump to another worktree",
+ "body": "Run wt switch to open a picker: type to filter, move with the arrow keys, Enter to switch, Esc to leave. Mark this step done when you've tried it.",
+ "kind": "manual",
+ "match_mode": "exact",
+ "pattern": null,
+ "output_contains": null,
+ "require_success": false,
+ "optional": true
+ }
+ ]
+}
diff --git a/docs/demos/demoshell/recipe.sh b/docs/demos/demoshell/recipe.sh
new file mode 100644
index 000000000..2c25fc79e
--- /dev/null
+++ b/docs/demos/demoshell/recipe.sh
@@ -0,0 +1,40 @@
+# Demoshell base image script for the Try it page (Alpine arm64, runs as root).
+# It installs the latest wt release and prepares the demo repository the guide
+# walks through; see README.md.
+
+set -eu
+
+apk add bash curl git less xz
+
+curl -fsSL https://github.com/max-sixty/worktrunk/releases/latest/download/worktrunk-aarch64-unknown-linux-musl.tar.xz \
+ | tar -xJ -C /tmp
+install -m 755 /tmp/worktrunk-aarch64-unknown-linux-musl/wt /usr/local/bin/wt
+rm -rf /tmp/worktrunk-aarch64-unknown-linux-musl
+
+# Studio launches bash explicitly with after-load.sh as its rcfile; changing
+# root's login shell would not change Demoshell's running ash session.
+# Demoshell's command tracker requires the arm64js: prompt prefix.
+echo 'PS1='"'"'arm64js:\[\e[32m\]\W\[\e[0m\] $ '"'" > "$HOME/.bashrc"
+wt config shell install bash --yes
+
+git config --global user.name "Demo User"
+git config --global user.email [email protected]
+git config --global init.defaultBranch main
+mkdir -p "$HOME/.config/worktrunk"
+echo 'skip-commit-generation-prompt = true' > "$HOME/.config/worktrunk/config.toml"
+
+# A small repository with two worktrees already in flight, so the first
+# `wt list` has something to show: `docs` is a commit ahead of main, and
+# `experiment` has uncommitted changes.
+mkdir "$HOME/acme"
+cd "$HOME/acme"
+git init -q
+printf '# Acme\n\nPricing for the Acme app.\n' > README.md
+printf 'Starter: $19/month\nTeam: $49/month\n' > pricing.txt
+git add .
+git commit -qm "Add pricing"
+wt switch --create docs --no-cd --yes
+printf '\nPrices are billed monthly.\n' >> ../acme.docs/README.md
+git -C ../acme.docs commit -qam "Note monthly billing"
+wt switch --create experiment --no-cd --yes
+printf 'Enterprise: contact us\n' >> ../acme.experiment/pricing.txt
diff --git a/docs/src/pages/try-it.astro b/docs/src/pages/try-it.astro
new file mode 100644
index 000000000..a2b8ed6d5
--- /dev/null
+++ b/docs/src/pages/try-it.astro
@@ -0,0 +1,87 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+
+// The demo VM and its guide are defined in docs/demos/demoshell/. `snapshot`
+// is the VM's Demoshell reference; it changes if the VM moves to another
+// Demoshell org or is renamed.
+const server = 'https://build.demoshell.com';
+const snapshot = 'm/tui:worktrunk';
+const launchUrl = `${server}/launch?snapshot=${encodeURIComponent(snapshot)}`;
+---
+
+<StarlightPage
+ frontmatter={{
+ title: 'Try it',
+ description: 'Run Worktrunk in your browser: a Linux VM with wt installed and a guided walk through creating, merging, and removing a worktree.',
+ editUrl: false,
+ tableOfContents: false,
+ pagefind: false,
+ head: [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex' } }],
+ }}
+>
+ <p>
+ Run Worktrunk in a Linux VM inside this browser tab — no install, and nothing
+ you type leaves your machine. The guide beside the terminal walks through a
+ worktree's whole life: create one, change a file, and merge it back to
+ <code>main</code>.
+ </p>
+ <p>
+ Nothing downloads until you press run. Chrome and Edge run the VM in the
+ page. <a href={launchUrl}>Open the full-page demo</a> if your browser cannot
+ run it here.
+ </p>
+
+ <div class="wt-try-it" data-server={server} data-snapshot={snapshot}>
+ <noscript>
+ <p><a href={launchUrl}>Open the demo</a> — it needs JavaScript.</p>
+ </noscript>
+ </div>
+ <p class="wt-try-it-credit">
+ Powered by <a href="https://demoshell.com">Demoshell</a>.
+ </p>
+
+ <p>
+ Ready for the real thing? <a href="/#install">Install Worktrunk</a>, then run
+ <code>wt config shell install</code> so <code>wt switch</code> can change
+ directory.
+ </p>
+</StarlightPage>
+
+<style>
+ /* The embed fills its container, so the container needs a definite height:
+ room for the terminal with the guide stacked under it. */
+ .wt-try-it {
+ height: 640px;
+ }
+
+ .wt-try-it-credit {
+ font-size: var(--sl-text-sm);
+ color: var(--sl-color-gray-3);
+ text-align: right;
+ }
+</style>
+
+<script is:inline type="module">
+ const target = document.querySelector('.wt-try-it');
+ const currentTheme = () => (document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light');
+
+ try {
+ const { default: Demoshell } = await import(`${target.dataset.server}/embed/demoshell-embed.js`);
+ const demo = await Demoshell.mount(target, {
+ snapshot: target.dataset.snapshot,
+ server: target.dataset.server,
+ theme: currentTheme(),
+ });
+ // Follow the site's theme toggle, as the page around the demo does.
+ new MutationObserver(() => demo.setTheme?.(currentTheme())).observe(document.documentElement, {
+ attributes: true,
+ attributeFilter: ['data-theme'],
+ });
+ } catch (error) {
+ const link = document.createElement('a');
+ link.href = `${target.dataset.server}/launch?snapshot=${encodeURIComponent(target.dataset.snapshot)}`;
+ link.textContent = 'Open the demo on Demoshell';
+ target.replaceChildren(link);
+ console.error('[try-it] demo failed to load', error);
+ }
+</script>
diff --git a/docs/tests/built-site.test.mjs b/docs/tests/built-site.test.mjs
index b843f10ff..bad3c66e4 100644
--- a/docs/tests/built-site.test.mjs
+++ b/docs/tests/built-site.test.mjs
@@ -28,6 +28,7 @@ const publicRoutes = [
'/step/',
'/switch/',
'/tips-patterns/',
+ '/try-it/',
];
async function htmlFiles(directory = dist) {
@@ -116,10 +117,10 @@ test('build preserves the public route contract', async () => {
for (const file of expected) assert.ok(files.has(file), `missing ${file}`);
const sitemap = await readFile(path.join(dist, 'sitemap-0.xml'), 'utf8');
- for (const route of publicRoutes) {
+ for (const route of publicRoutes.filter((route) => route !== '/try-it/')) {
assert.match(sitemap, new RegExp(`<loc>https://worktrunk\\.dev${route}</loc>`));
}
- assert.doesNotMatch(sitemap, /worktrunk\.dev\/(?:404|worktrunk)\//);
+ assert.doesNotMatch(sitemap, /worktrunk\.dev\/(?:404|worktrunk|try-it)\//);
const robots = await readFile(path.join(dist, 'robots.txt'), 'utf8');
for (const match of robots.matchAll(/^Sitemap:\s+(\S+)$/gm)) {
@@ -562,7 +563,8 @@ test('hash navigation selects the requested section in every rendered TOC', () =
});
test('every structural content heading appears in the page outline', async () => {
- for (const route of publicRoutes.filter((candidate) => candidate !== '/')) {
+ // The homepage and the Try it page drop the outline to give content the width.
+ for (const route of publicRoutes.filter((candidate) => !['/', '/try-it/'].includes(candidate))) {
const page = await readFile(routeFile(route), 'utf8');
const headings = [...page.matchAll(/<h[12]\b[^>]*\bid="([^"]+)"/g)]
.map((match) => match[1])
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 7244adfcb..fb3db4048 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -2863,6 +2863,8 @@ fn test_no_nested_auto_generated_markers() {
///
/// Only pages the sidebar names are checked. A page may carry an order without
/// a sidebar entry (`code-signing.md`); the order still places it in llms.txt.
+/// An Astro page (`docs/src/pages/try-it.astro`) is not in llms.txt, so it has
+/// no order to agree with.
#[test]
fn test_sidebar_matches_frontmatter_order() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
@@ -2881,6 +2883,11 @@ fn test_sidebar_matches_frontmatter_order() {
"" => "worktrunk".to_string(),
slug => slug.to_string(),
})
+ .filter(|slug| {
+ !project_root
+ .join(format!("docs/src/pages/{slug}.astro"))
+ .exists()
+ })
.collect();
assert!(