Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions infrastructure/.gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
.tools/
node_modules/
.local/
.design-gallery/
**/.terraform/
**/*.tfstate*
**/*.tfplan
Expand Down
2 changes: 2 additions & 0 deletions infrastructure/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ Every full-screen launch welcomes you with a cyan ASCII GitHub mark and magenta

The wizard uses a separate terminal screen and restores your shell on completion, cancellation, and catchable errors. Use Page Up and Page Down to scroll long notices or approval details. Narrow screens show the current stage and position instead of the full map. Use `npm run setup:server -- --no-fullscreen` for inline mode. Limited terminals and `INK_SCREEN_READER=true` also use inline mode, without welcome art or an animated timer.

For offline design work, run `npm run wizard:design --prefix infrastructure` from the repository root after installing the infrastructure development dependencies. Open its loopback capture page in a browser to regenerate the 100-state synthetic screen gallery, individual PNGs and annotated PDF. See [the design capture workflow](docs/terminal-design.md#regenerate-the-wizard-design-gallery) for setup, output paths and catalog maintenance. This command never starts a deployment or reads private installation files.

From the repository root, install the wizard's dependencies and start it:

```sh
Expand Down
22 changes: 22 additions & 0 deletions infrastructure/docs/terminal-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,28 @@ Use existing Vitest and Ink testing tools. Follow the [test-writing skill](../..

Use rendered terminal review for color, spacing, hierarchy, and the subtlety of the map and timer. Do not freeze cosmetic ANSI output or exact artwork in broad snapshots. Use isolated sample-data previews for visual checks; these do not prove an authenticated Azure deployment.

### Regenerate the wizard design gallery

From the repository root, install the infrastructure development dependencies with the approved npm registry, then start the capture command:

```sh
npm ci --prefix infrastructure --ignore-scripts --engine-strict \
--registry=https://packagefeedproxy.microsoft.io/npm/ --replace-registry-host=never
npm run wizard:design --prefix infrastructure
```

Open the complete printed `http://127.0.0.1:PORT/#token=...` address in an ordinary browser, including its access fragment. Keep this per-run link private; opening the address without its fragment cannot export. Use **Previous**, the screen selector and **Next** to browse the screen and its side-by-side annotations. Choose **Generate all screens and PDF** to export the whole catalog; the page returns to your selected screen afterwards. Navigation and export cannot overlap, and controls stay disabled until the current render or export finishes. Keep the page and command open until it reports completion. The command does not install or launch a browser and does not require the Copilot browser host. Stop its local server with Ctrl+C after export.

Each run creates an ignored `infrastructure/.design-gallery/run-*/` directory containing `index.html`, `gallery.css`, `manifest.json`, `screens/` with individual PNGs and visible-text transcripts, and `Replica-wizard-design-guide.pdf`. Open `index.html` directly for offline design review, or share that whole directory. The live and offline gallery share their layout and navigation. The PDF has linked contents and one annotated screen per page. Incomplete captures and invalid images fail instead of producing a partial PDF.

The maintained catalog in [`installer/design-gallery/scenes.ts`](../installer/design-gallery/scenes.ts) covers 100 distinct states: direct prompt families and representative branching, validation, recovery, result, scrolling and responsive variants. Each screen records its purpose, required decision or default, consequence and source. Catalog array position supplies the displayed number everywhere, including dropdown, Previous/Next navigation, manifest and PDF. Semantic IDs are stable file names and links, not ordinals; keep related recovery variants in their chapter rather than preserving old screenshot numbers.

The command renders the real `TerminalShell` and its input components into isolated streams. Scripted key events exercise filtering, validation and scrolling. Field scenes use `configurationFields`; receipt scenes call `formatDeploymentSummary` with a fabricated `DeploymentResult`. Other shell output and cloud responses are explicit synthetic fixtures. The tool does not run wizard orchestration, Azure CLI, Docker, Terraform, deployment or release scripts, database jobs, sign-in or lock recovery, and never loads `.local/` configuration or diagnostics. Inline presentation is illustrated, not audited with assistive technology.

When adding or changing prompt behavior, update the catalog's inputs and annotations together. Source-copy bindings in `scenes.ts` contain SHA-256 hashes of the production files supplying fixture copy. Generation stops if one changes; review every affected scene before updating its binding. For example, from the repository root, `shasum -a 256 infrastructure/azure/install/configure/index.ts` prints that file's current hash. Presentation-only changes to the shell render directly without refreshing copied messages. Regenerate and inspect the affected screens after either kind of change; a source hash is a review reminder, not proof that annotations are correct.

The capture server listens only on loopback, serves fixed assets and catalog output paths, and accepts exports only from its exact origin with a per-run token. The command supplies that token through the printed URL fragment, which the browser does not send in HTTP requests; the unauthenticated catalog and assets never return it. Do not share the access link or expose or forward its port. It has no deployment controls. Output directories are unique per run; remove old runs when they are no longer needed.

## Maintaining the patterns

Keep this document as the rationale and implemented pattern guide. All five delivery phases above are implemented. Label future proposals separately from current behavior and update these contracts as they settle.
Expand Down
38 changes: 38 additions & 0 deletions infrastructure/installer/design-gallery/capture.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Replica wizard design capture</title>
<link rel="stylesheet" href="/assets/xterm.css">
<link rel="stylesheet" href="/assets/gallery.css">
<header>
<h1>Replica Hub installation wizard</h1>
<p id="summary">Synthetic states · no Azure commands · real Ink presentation</p>
<nav aria-label="Screen navigation">
<button id="previous" disabled>Previous</button>
<select id="scene" aria-label="Screen" disabled></select>
<button id="next" disabled>Next</button>
<button id="generate" disabled>Generate all screens and PDF</button>
</nav>
<p id="status" role="status" aria-live="polite">Loading synthetic screens...</p>
<div id="result"></div>
</header>
<main>
<section>
<h2 id="title"></h2>
<div id="viewport"><div id="terminal-scale"><div id="terminal-frame"><div id="terminal"></div></div></div></div>
<p class="screen-links"><a id="original" hidden>Original 2x PNG</a><a id="transcript" hidden>Visible terminal transcript</a></p>
<details><summary>Visible terminal text</summary><pre id="visible-text"></pre></details>
</section>
<aside aria-label="Screen annotations">
<p id="group"></p>
<dl id="notes"></dl>
<small id="source"></small>
<p id="page"></p>
<p>Staged terminal state, not a live cloud deployment. Sign-in, authorization and accessibility are not audited.</p>
</aside>
</main>
<script src="/assets/xterm.js"></script>
<script src="/assets/html-to-image.js"></script>
<script src="/assets/capture.js"></script>
</html>
160 changes: 160 additions & 0 deletions infrastructure/installer/design-gallery/capture.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
/* global Terminal, htmlToImage */
const status = document.getElementById("status")
const select = document.getElementById("scene")
const generate = document.getElementById("generate")
const previous = document.getElementById("previous")
const next = document.getElementById("next")
const frame = document.getElementById("terminal-frame")
const terminal = new Terminal({
cols: 112, rows: 38, convertEol: true, disableStdin: true,
fontFamily: "Menlo, Monaco, Consolas, monospace", fontSize: 16, lineHeight: 1.15,
cursorBlink: false, scrollback: 1000,
theme: { background: "#0d1117", foreground: "#e6edf3", cursor: "#0d1117" },
})
terminal.open(document.getElementById("terminal"))
let scenes
let token
let current = 0
let busy = true
let exported = false

function controls() {
select.disabled = busy
previous.disabled = busy || current === 0
next.disabled = busy || current === scenes.length - 1
generate.disabled = busy || exported
}

function fitPreview() {
const viewport = document.getElementById("viewport")
const scale = Math.min(1, viewport.clientWidth / frame.offsetWidth)
document.getElementById("terminal-scale").style.transform = `scale(${scale})`
viewport.style.height = `${frame.offsetHeight * scale}px`
}

new ResizeObserver(fitPreview).observe(document.getElementById("viewport"))

function visibleText() {
const buffer = terminal.buffer.active
return Array.from({ length: terminal.rows }, (_, row) =>
buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? "",
).join("\n").trimEnd()
}

async function show(scene) {
current = scenes.indexOf(scene)
select.value = scene.id
terminal.reset()
terminal.resize(scene.columns, scene.rows)
await new Promise(resolve => terminal.write(`\x1b[2J\x1b[H${scene.ansi}\x1b[?25l`, resolve))
await document.fonts.ready
await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))
fitPreview()
document.getElementById("title").textContent = `${String(scene.ordinal).padStart(3, "0")} / ${scene.title}`
document.getElementById("group").textContent = scene.group
document.getElementById("source").textContent = `Source: ${scene.source}\nStable ID: ${scene.id}`
document.getElementById("page").textContent = `PDF page ${2 + Math.ceil(scenes.length / 25) + current}`
const notes = document.getElementById("notes")
notes.replaceChildren()
for (const [heading, key] of [["Purpose", "purpose"], ["Decision / input", "decision"], ["Consequence / next", "consequence"]]) {
const dt = document.createElement("dt")
const dd = document.createElement("dd")
dt.textContent = heading
dd.textContent = scene[key]
notes.append(dt, dd)
}
document.getElementById("visible-text").textContent = visibleText()
for (const [id, extension] of [["original", "png"], ["transcript", "txt"]]) {
const link = document.getElementById(id)
link.hidden = !exported
link.href = `/gallery/screens/${scene.id}.${extension}`
}
history.replaceState(null, "", `#${new URLSearchParams({ token, scene: scene.id })}`)
}

async function post(path, body) {
const response = await fetch(path, {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
body: JSON.stringify(body),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error ?? `Export failed (${response.status}).`)
return result
}

generate.onclick = async () => {
if (busy || exported) return
const selected = current
busy = true
controls()
try {
for (const scene of scenes) {
status.textContent = `Capturing ${scene.ordinal} of ${scenes.length}: ${scene.title}`
await show(scene)
const png = await htmlToImage.toPng(frame, { pixelRatio: 2, skipFonts: true })
const transcript = visibleText()
await post(`/capture/${scene.id}`, { png, transcript })
}
status.textContent = "Creating offline gallery and annotated PDF..."
const result = await post("/finish", {})
exported = true
status.textContent = `Complete: ${scenes.length} screens.\n${result.directory}`
for (const [label, href] of [["Open offline gallery", result.gallery], ["Open annotated PDF", result.pdf]]) {
const link = document.createElement("a")
link.textContent = label
link.href = href
document.getElementById("result").append(link)
}
} catch (error) {
status.textContent = `Generation failed: ${error.message}`
} finally {
await show(scenes[selected])
busy = false
controls()
}
}

async function navigate(index) {
if (busy) return
busy = true
controls()
try {
await show(scenes[Math.max(0, Math.min(scenes.length - 1, index))])
} catch (error) {
status.textContent = `Preview failed: ${error.message}`
} finally {
busy = false
controls()
}
}

select.onchange = () => navigate(scenes.findIndex(scene => scene.id === select.value))
previous.onclick = () => navigate(current - 1)
next.onclick = () => navigate(current + 1)

async function load() {
const access = new URLSearchParams(location.hash.slice(1))
token = access.get("token")
if (!token || !/^[a-f0-9]{64}$/.test(token)) {
throw new Error("Open the complete URL printed by wizard:design, including its access fragment.")
}
const response = await fetch("/scenes.json")
if (!response.ok) throw new Error(`Could not load catalog (${response.status}).`)
const data = await response.json()
scenes = data.scenes
for (const scene of scenes) {
const option = document.createElement("option")
option.value = scene.id
option.textContent = scene.label
select.append(option)
}
document.getElementById("summary").textContent = `${scenes.length} synthetic states · source ${data.revision} · no Azure commands · real Ink presentation`
const initial = scenes.findIndex(scene => scene.id === access.get("scene"))
await show(scenes[initial < 0 ? 0 : initial])
status.textContent = "Browse the screens, or generate the complete offline gallery and PDF. Keep this page open during export."
busy = false
controls()
}

load().catch(error => { status.textContent = `Capture page failed: ${error.message}` })
Loading
Loading