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.mjsindex 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.mdnew file mode 100644index 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.shnew file mode 100644index 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.jsonnew file mode 100644index 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.shnew file mode 100644index 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.txtdiff --git a/docs/src/pages/try-it.astro b/docs/src/pages/try-it.astronew file mode 100644index 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.mjsindex 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.rsindex 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!(