sitevision-cli 1.0.0-beta.30 → 1.0.0-beta.32

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.0.0-beta.32
+
+- Sitevision CLI can now create new apps. **New app** in the command palette
+  runs Sitevision's own `create-sitevision-app` as a managed experience and
+  guides you through the setup: pick a name and a folder, then answer the
+  tool's questions right in `svc`. What your workspace already knows (domain,
+  site name, username) is filled in for you, and passwords never end up in a
+  file.
+- When the app is created, `svc` fills in its manifest (the name, plus author
+  and help URL from the workspace's `package.json`) and offers to create the
+  addon on the site, so the app is ready for its first deploy.
+- If the tool cannot be run this way, `svc` hands it the terminal and picks up
+  again when it is done.
+- The Config tab has a MANIFEST section for editing `manifest.json`: id,
+  version, name, description, author and help URL, one row per language for
+  localized fields. Comments and formatting in the file are kept.
+- `y` (sync `package.json`) now also mirrors the manifest's `version`,
+  `description` and `author` into the app's `package.json`. An app whose
+  `package.json` lacks them shows as out of sync until `y` is pressed.
+
+## 1.0.0-beta.31
+
+- The help panel (`?`) now starts with a short guide to the pane you are in:
+  what it shows, how the values relate, and which keys apply. The Config guide
+  explains how local, shared and workspace settings layer on top of each
+  other. The panel scrolls when it does not fit.
+- Updated dependencies.
+
 ## 1.0.0-beta.30
 
 - Dev and watch no longer rebuild on file events that change nothing, such as

package/dist/cli.js

@@ -157,8 +157,26 @@ async function runShell(apps, workspaceRoot, updatedFrom) {
             await playIntro(art);
             process.stdout.write('\x1b[2J\x1b[H');
         }
-        const app = render(_jsx(Shell, { apps: apps, workspaceRoot: workspaceRoot, version: pkg.version, minimal: cli.flags.minimal, updatedFrom: updatedFrom }));
-        await app.waitUntilExit();
+        // A handover unmounts the shell, runs its job on the normal screen with
+        // the terminal to itself, and starts the shell again.
+        for (;;) {
+            let job;
+            const app = render(_jsx(Shell, { apps: apps, workspaceRoot: workspaceRoot, version: pkg.version, minimal: cli.flags.minimal, updatedFrom: updatedFrom, handover: next => {
+                    job = next;
+                    app.unmount();
+                } }));
+            // eslint-disable-next-line no-await-in-loop
+            await app.waitUntilExit();
+            if (!job)
+                break;
+            process.stdout.write('\x1b[?1049l');
+            // eslint-disable-next-line no-await-in-loop
+            await job();
+            if (workspaceRoot)
+                apps = discoverApps(workspaceRoot);
+            updatedFrom = undefined;
+            process.stdout.write('\x1b[?1049h\x1b[2J\x1b[H');
+        }
     }
     finally {
         process.stdout.write('\x1b[?1049l');

package/dist/scaffold/inquirer-stub.d.ts

@@ -0,0 +1,6 @@
+type Answers = Record<string, unknown>;
+declare function prompt(questions: unknown, initial?: Answers): Promise<Answers>;
+declare const inquirer: {
+    prompt: typeof prompt;
+};
+export default inquirer;

package/dist/scaffold/inquirer-stub.js

@@ -0,0 +1,119 @@
+/**
+ * Stands in for inquirer inside the scaffolder: every question goes to svc over
+ * the socket in SVC_PROMPT_SOCKET and the reply comes back as the answer. `when`,
+ * `filter`, `validate` and function-valued fields run here, where they live.
+ * Self-contained on purpose: it is loaded by the tool's node, not by svc.
+ */
+import net from 'node:net';
+import process from 'node:process';
+import readline from 'node:readline';
+const CHOICE_TYPES = new Set(['list', 'rawlist', 'expand', 'select', 'search']);
+const evaluate = async (field, ...args) => typeof field === 'function' ? (await field(...args)) : field;
+const text = (value) => typeof value === 'string' ? value : JSON.stringify(value);
+function normalizeChoices(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const choices = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== 'object') {
+            choices.push({ name: text(entry), value: entry, checked: false });
+            continue;
+        }
+        const choice = entry;
+        if (choice['type'] === 'separator' || choice['disabled'])
+            continue;
+        const value = 'value' in choice ? choice['value'] : choice['name'];
+        choices.push({
+            name: text(choice['name'] ?? value),
+            value,
+            checked: Boolean(choice['checked']),
+        });
+    }
+    return choices;
+}
+/** Ask svc until the tool's own validation accepts; undefined when skipped. */
+async function askOne(question, answers, exchange) {
+    const type = text(question['type'] ?? 'input');
+    const choices = normalizeChoices(await evaluate(question['choices'], answers));
+    const fallback = await evaluate(question['default'], answers);
+    const values = choices.map(choice => choice.value);
+    const message = text(await evaluate(question['message'], answers));
+    let initial = fallback;
+    if (type === 'checkbox') {
+        const preset = Array.isArray(fallback) ? fallback : [];
+        initial = choices.flatMap((choice, i) => choice.checked || preset.includes(choice.value) ? [i] : []);
+    }
+    else if (CHOICE_TYPES.has(type)) {
+        // Inquirer takes a default as either the value or its index.
+        const at = values.indexOf(fallback);
+        initial = at === -1 && typeof fallback === 'number' ? fallback : at;
+        initial = Math.max(0, initial);
+    }
+    let error;
+    for (;;) {
+        // eslint-disable-next-line no-await-in-loop
+        const reply = await exchange({
+            name: question.name,
+            type,
+            message,
+            choices: choices.map(choice => choice.name),
+            default: initial,
+            error,
+        });
+        if (reply.skip)
+            return undefined;
+        let { value } = reply;
+        if (type === 'checkbox')
+            value = value.map(i => values[i]);
+        else if (CHOICE_TYPES.has(type))
+            value = values[value];
+        else if (type === 'number')
+            value = Number(value);
+        // eslint-disable-next-line no-await-in-loop
+        value = await evaluate(question['filter'] ?? value, value, answers);
+        // eslint-disable-next-line no-await-in-loop
+        const valid = await evaluate(question['validate'] ?? true, value, answers);
+        if (valid === true)
+            return value;
+        error = typeof valid === 'string' ? valid : 'Invalid value';
+    }
+}
+async function prompt(questions, initial = {}) {
+    const list = Array.isArray(questions)
+        ? questions
+        : typeof questions.name === 'string'
+            ? [questions]
+            : Object.entries(questions).map(([name, question]) => ({ ...question, name }));
+    const socket = net.connect(process.env['SVC_PROMPT_SOCKET']);
+    const lines = readline.createInterface({ input: socket });
+    const replies = lines[Symbol.asyncIterator]();
+    const exchange = async (message) => {
+        socket.write(JSON.stringify(message) + '\n');
+        const next = await replies.next();
+        if (next.done)
+            throw new Error('svc closed the prompt');
+        return JSON.parse(next.value);
+    };
+    // ponytail: dotted names ("a.b") stay flat keys; nest them if a question ever uses one.
+    const answers = { ...initial };
+    try {
+        for (const question of list) {
+            const wanted = question['when'] === undefined ||
+                // eslint-disable-next-line no-await-in-loop
+                Boolean(await evaluate(question['when'], answers));
+            const answered = answers[question.name] !== undefined && !question['askAnswered'];
+            if (!wanted || answered)
+                continue;
+            // eslint-disable-next-line no-await-in-loop
+            const value = await askOne(question, answers, exchange);
+            if (value !== undefined)
+                answers[question.name] = value;
+        }
+    }
+    finally {
+        socket.end();
+    }
+    return answers;
+}
+const inquirer = { prompt };
+export default inquirer;

package/dist/scaffold/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scaffold/register.js

@@ -0,0 +1,15 @@
+// Loaded through NODE_OPTIONS into every process the scaffolder starts: hands
+// sitevision-scripts svc's prompt bridge in place of inquirer.
+import module from 'node:module';
+import path from 'node:path';
+const stub = new URL(`inquirer-stub${path.extname(import.meta.url)}`, import.meta.url).href;
+// Missing before Node 22.15; svc then finds the run unmanaged and falls back.
+module.registerHooks?.({
+    resolve(specifier, context, nextResolve) {
+        if (specifier === 'inquirer' &&
+            context.parentURL?.includes('sitevision-scripts')) {
+            return { url: stub, shortCircuit: true };
+        }
+        return nextResolve(specifier, context);
+    },
+});

package/dist/shell/ConfigForm.d.ts

@@ -1,4 +1,4 @@
-import type { DevProperties } from '../types/index.js';
+import type { DevProperties, SitevisionManifest } from '../types/index.js';
 type Method = 'basic' | 'oauth2' | 'cookie';
 interface Field {
     key: string;
@@ -10,7 +10,11 @@ interface Field {
     hint?: string;
     perApp?: boolean;
     help: string;
+    manifestKey?: string;
+    lang?: string;
 }
+/** Rows for manifest.json: one per text field, one per language of a localized one. */
+export declare function manifestFields(manifest?: SitevisionManifest): Field[];
 type Values = Record<string, string>;
 /** What the form edits: an app, or the workspace root (no addon, no package.json). */
 export interface ConfigTarget {
@@ -20,6 +24,8 @@ export interface ConfigTarget {
     environment?: string;
     workspace?: boolean;
     workspaceRoot?: string;
+    manifest?: SitevisionManifest;
+    manifestPath?: string;
 }
 /** Apply the form to disk and the keychain. Exported for the test. */
 export declare function saveConfig(project: ConfigTarget, values: Values, edited: Set<string>): void;

package/dist/shell/ConfigForm.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
-import { findDevPropertiesPath, getPackageJsonSyncChanges, hasPackageJson, IMPLICIT_VALUES, normalizeDomain, readAncestorDevProperties, readInheritedDevProperties, readWorkspaceDevProperties, updatePackageJson, writeDevProperties, } from '../utils/project-detection.js';
+import { findDevPropertiesPath, getPackageJsonSyncChanges, hasPackageJson, IMPLICIT_VALUES, normalizeDomain, readAncestorDevProperties, readInheritedDevProperties, readWorkspaceDevProperties, updatePackageJson, writeDevProperties, writeManifestField, } from '../utils/project-detection.js';
 import { setDeployPassword, deleteDeployPassword, getOAuth2ClientSecret, setOAuth2ClientSecret, deleteOAuth2ClientSecret, getSigningPassword, setSigningPassword, deleteSigningPassword, } from '../utils/keychain.js';
 import { DEFAULT_SCOPES, discoverOAuth2Config } from '../utils/oauth2-auth.js';
 import { ACCENT } from './Frame.js';
@@ -132,6 +132,61 @@ const FIELDS = [
         hint: 'blank = prompt each run',
     },
 ];
+const MANIFEST_FIELDS = [
+    {
+        key: 'id',
+        label: 'App id',
+        required: true,
+        help: 'Identifier of the app in Sitevision; it also names the zip. Changing it makes the next deploy a new app instead of an update.',
+    },
+    {
+        key: 'version',
+        label: 'Version',
+        required: true,
+        help: 'Version of the app. Id and version together identify an upload, so bump it to deploy a new version instead of overwriting the current one.',
+    },
+    {
+        key: 'name',
+        label: 'Name',
+        required: true,
+        help: 'Name shown when importing and administering the app in the Sitevision editor. A multilingual manifest needs at least English.',
+    },
+    {
+        key: 'description',
+        label: 'Description',
+        help: 'Short description shown next to the name in the Sitevision editor.',
+    },
+    {
+        key: 'author',
+        label: 'Author',
+        help: 'Who made the app, shown in the Sitevision editor.',
+    },
+    {
+        key: 'helpUrl',
+        label: 'Help URL',
+        help: "Link to the app's documentation, shown in the Sitevision editor.",
+    },
+];
+/** Rows for manifest.json: one per text field, one per language of a localized one. */
+export function manifestFields(manifest) {
+    if (!manifest)
+        return [];
+    const raw = manifest;
+    return MANIFEST_FIELDS.flatMap(f => {
+        const value = raw[f.key];
+        const base = { ...f, section: 'MANIFEST', manifestKey: f.key };
+        if (value && typeof value === 'object') {
+            return Object.keys(value).map(lang => ({
+                ...base,
+                key: `manifest.${f.key}.${lang}`,
+                lang,
+                required: f.required && lang === 'en',
+            }));
+        }
+        return [{ ...base, key: `manifest.${f.key}` }];
+    });
+}
+const labelOf = (f) => t(f.label) + (f.lang ? ` (${f.lang})` : '');
 const ENV_KEYS = new Set([
     'domain',
     'siteName',
@@ -170,6 +225,13 @@ function fromProject(project) {
         signingUsername: dev.signingUsername ?? '',
         certificateName: dev.certificateName ?? '',
         signingPassword: '',
+        ...Object.fromEntries(manifestFields(project.manifest).map(f => {
+            const value = project.manifest[f.manifestKey];
+            const text = f.lang
+                ? value[f.lang]
+                : value;
+            return [f.key, typeof text === 'string' ? text : ''];
+        })),
     };
 }
 function storedSecret(project, key) {
@@ -325,28 +387,41 @@ export function ConfigForm({ project, active, width, height, pickAddon, onSaved,
     const envMode = Boolean(project.environment &&
         project.environment !==
             baseEnvironment(project.base ?? project.devProperties));
-    const fields = visibleFields(method, project.workspace, envMode);
+    const fields = [
+        ...visibleFields(method, project.workspace, envMode),
+        ...manifestFields(project.manifest),
+    ];
     const current = fields[Math.min(cursor, fields.length - 1)];
     const inherited = readInheritedDevProperties(project.root);
     const ancestors = readAncestorDevProperties(project.root);
     const changes = getPackageJsonSyncChanges(project.root);
     const packageJsonExists = hasPackageJson(project.root);
     // Write one field to disk (and the keychain for secrets) right away.
-    const commit = (key, value, label = current.label) => {
+    const commit = (key, value, label = labelOf(current)) => {
         const clean = key === 'domain' ? normalizeDomain(value) : value;
+        const field = fields.find(f => f.key === key);
+        if (field?.manifestKey && field.required && !clean) {
+            setNote(t('Not saved: {label} is required.', { label }));
+            return;
+        }
         const next = { ...values, [key]: clean };
         setValues(next);
         try {
-            saveConfig(project, next, new Set([key]));
+            if (field?.manifestKey) {
+                writeManifestField(project.manifestPath, field.manifestKey, clean, field.lang);
+            }
+            else {
+                saveConfig(project, next, new Set([key]));
+            }
         }
         catch (error) {
             setNote(t('Not saved: {error}', { error: errorText(error) }));
             return;
         }
         setNote(clean === value
-            ? t('Saved {label}.', { label: t(label) })
+            ? t('Saved {label}.', { label })
             : t('Saved {label} as {value} — a domain is a host only.', {
-                label: t(label),
+                label,
                 value: clean,
             }));
         onSaved();
@@ -394,7 +469,7 @@ export function ConfigForm({ project, active, width, height, pickAddon, onSaved,
         void pickAddon().then(name => {
             if (name) {
                 setEditing(false);
-                commit('addonName', name, 'Addon name');
+                commit('addonName', name, t('Addon name'));
             }
         });
     };
@@ -468,6 +543,8 @@ export function ConfigForm({ project, active, width, height, pickAddon, onSaved,
         if (f.kind === 'secret') {
             return { text: storedSecret(project, f.key) ? t('keychain') : '—' };
         }
+        if (f.manifestKey)
+            return { text: (values[f.key] ?? '') ? 'manifest.json' : '' };
         const value = f.kind === 'bool' ? values[f.key] === 'yes' : values[f.key];
         if (envMode && ENV_KEYS.has(f.key)) {
             const override = project.base?.environments?.[project.environment];
@@ -507,12 +584,15 @@ export function ConfigForm({ project, active, width, height, pickAddon, onSaved,
     // label column (24) + source column + paddings; never below 20.
     const valueWidth = Math.max(20, width - 24 - SOURCE_WIDTH - 2);
     const rows = [];
+    let focusRow = 0;
     let lastSection;
     for (const f of fields) {
         if (f.section && f.section !== lastSection) {
-            rows.push(_jsx(Box, { marginTop: 1, flexShrink: 0, children: _jsx(Text, { bold: true, dimColor: true, children: t(f.section) }) }, `s-${f.section}`));
+            rows.push(_jsx(Box, { height: 1, flexShrink: 0 }, `g-${f.section}`), _jsx(Box, { height: 1, flexShrink: 0, children: _jsx(Text, { bold: true, dimColor: true, children: t(f.section) }) }, `s-${f.section}`));
             lastSection = f.section;
         }
+        if (f === current)
+            focusRow = rows.length;
         const focused = active && f === current;
         const typing = focused && editing;
         // A value being typed into, scrolled so the caret stays in view and drawn
@@ -544,9 +624,13 @@ export function ConfigForm({ project, active, width, height, pickAddon, onSaved,
             display = typing ? (withCaret(draft)) : value ? (_jsx(Text, { children: value })) : (_jsx(Text, { dimColor: true, children: f.hint ? t(f.hint) : '—' }));
         }
         const src = source(f);
-        rows.push(_jsxs(Box, { height: 1, flexShrink: 0, children: [_jsx(Text, { color: focused ? ACCENT : undefined, bold: focused, dimColor: !focused, children: (focused ? '▸ ' : '  ') + t(f.label).padEnd(22) }), _jsx(Box, { width: valueWidth, flexShrink: 0, children: _jsx(Text, { wrap: "truncate", children: display }) }), _jsx(Box, { width: SOURCE_WIDTH, flexShrink: 0, children: _jsx(Text, { dimColor: !src.color, color: src.color, wrap: "truncate", children: focused && f.hint && f.key === 'addonName' ? t(f.hint) : src.text }) })] }, f.key));
+        rows.push(_jsxs(Box, { height: 1, flexShrink: 0, children: [_jsx(Text, { color: focused ? ACCENT : undefined, bold: focused, dimColor: !focused, children: (focused ? '▸ ' : '  ') + labelOf(f).padEnd(22) }), _jsx(Box, { width: valueWidth, flexShrink: 0, children: _jsx(Text, { wrap: "truncate", children: display }) }), _jsx(Box, { width: SOURCE_WIDTH, flexShrink: 0, children: _jsx(Text, { dimColor: !src.color, color: src.color, wrap: "truncate", children: focused && f.hint && f.key === 'addonName' ? t(f.hint) : src.text }) })] }, f.key));
     }
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, overflow: "hidden", height: height, children: [_jsx(Box, { height: 1, flexShrink: 0, children: _jsxs(Text, { dimColor: true, wrap: "truncate", children: [('  ' + t('FIELD')).padEnd(24), t('VALUE').padEnd(valueWidth), t('SOURCE')] }) }), rows, project.workspace && (_jsx(Box, { marginTop: 1, flexShrink: 0, children: _jsx(Text, { dimColor: true, children: t("Shared by every app below {root}. An app's own value wins.", {
+    // ponytail: the help panel is assumed to wrap to three lines; measure it if
+    // a narrow pane ever clips the note.
+    const room = Math.max(3, height - 9 - changes.length - (project.workspace ? 2 : 0));
+    const firstRow = Math.max(0, Math.min(focusRow - Math.floor(room / 2), rows.length - room));
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, overflow: "hidden", height: height, children: [_jsx(Box, { height: 1, flexShrink: 0, children: _jsxs(Text, { dimColor: true, wrap: "truncate", children: [('  ' + t('FIELD')).padEnd(24), t('VALUE').padEnd(valueWidth), t('SOURCE')] }) }), rows.slice(firstRow, firstRow + room), project.workspace && (_jsx(Box, { marginTop: 1, flexShrink: 0, children: _jsx(Text, { dimColor: true, children: t("Shared by every app below {root}. An app's own value wins.", {
                         root: project.root,
                     }) }) })), _jsxs(Box, { marginTop: 1, flexDirection: "column", flexShrink: 0, children: [_jsxs(Text, { bold: true, dimColor: true, children: [t('PACKAGE.JSON SYNC'), ' ', _jsx(Text, { color: changes.length > 0 || !packageJsonExists ? 'yellow' : 'green', children: !packageJsonExists
                                     ? t('no workspace package.json · y to set up')
@@ -554,5 +638,5 @@ export function ConfigForm({ project, active, width, height, pickAddon, onSaved,
                                         ? t('in sync')
                                         : changes.length === 1
                                             ? t('1 diff · y to apply')
-                                            : t('{n} diffs · y to apply', { n: changes.length }) })] }), changes.map(c => (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: c.from === undefined ? 'green' : 'yellow', children: c.from === undefined ? '+ ' : '~ ' }), c.key, ": ", c.from !== undefined && _jsxs(Text, { dimColor: true, children: [c.from, " \u2192 "] }), c.to] }, c.key)))] }), _jsx(Box, { flexGrow: 1 }), _jsx(Box, { flexDirection: "column", borderStyle: "single", borderDimColor: true, borderLeft: false, borderRight: false, borderBottom: false, children: _jsxs(Text, { wrap: "wrap", children: [_jsx(Text, { bold: true, color: ACCENT, children: t(current.label) }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", t(current.help)] })] }) }), _jsx(Text, { color: "yellow", children: note })] }));
+                                            : t('{n} diffs · y to apply', { n: changes.length }) })] }), changes.map(c => (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: c.from === undefined ? 'green' : 'yellow', children: c.from === undefined ? '+ ' : '~ ' }), c.key, ": ", c.from !== undefined && _jsxs(Text, { dimColor: true, children: [c.from, " \u2192 "] }), c.to] }, c.key)))] }), _jsx(Box, { flexGrow: 1 }), _jsx(Box, { flexDirection: "column", borderStyle: "single", borderDimColor: true, borderLeft: false, borderRight: false, borderBottom: false, children: _jsxs(Text, { wrap: "wrap", children: [_jsx(Text, { bold: true, color: ACCENT, children: labelOf(current) }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", t(current.help)] })] }) }), _jsx(Text, { color: "yellow", children: note })] }));
 }

package/dist/shell/Help.d.ts

@@ -1,6 +1,9 @@
 import { type Hint } from './Frame.js';
-export declare function HelpPanel({ here, height, onClose, }: {
+import type { Tab } from './actions.js';
+export type Where = Tab | 'nav' | 'workspace';
+export declare function HelpPanel({ here, where, height, onClose, }: {
     here: Hint[];
+    where: Where;
     height: number;
     onClose: () => void;
 }): import("react").JSX.Element;

package/dist/shell/Help.js

@@ -1,9 +1,56 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Text, useInput } from 'ink';
+import { useEffect, useRef, useState } from 'react';
+import { Box, Text, measureElement, useInput } from 'ink';
 import { t } from '../utils/i18n.js';
 import { ACCENT } from './Frame.js';
 import { actions } from './actions.js';
 import { GROUPS } from './CommandPalette.js';
+// What the pane you are in does, beyond the key list. One entry per paragraph.
+const GUIDE = {
+    nav: {
+        title: 'Navigator',
+        text: [
+            'Typing filters the app list. ↑↓ move, Enter selects the app and moves focus to the content pane. Action keys such as d or p only work there; in the navigator they search.',
+            'The last row is Workspace settings: the shared root config that every app inherits.',
+        ],
+    },
+    workspace: {
+        title: 'Workspace settings',
+        text: [
+            "The root .dev_properties.json shared by every app, with the root package.json defaults underneath. Fill in site, auth and environments once; an app's own config overrides only what differs.",
+            'Same keys as the Config tab: Enter edits and saves, Esc cancels, ←→ or space cycles choices.',
+        ],
+    },
+    overview: {
+        title: 'Overview',
+        text: [
+            'Each status line names the key that fixes it: i installs dependencies, e opens Config, y syncs package.json, / sets up signing.',
+            'The badge in the top bar is the active environment: green for the base, yellow for others, red for production. v cycles it.',
+        ],
+    },
+    config: {
+        title: 'Config',
+        text: [
+            'Values come in layers and the source is shown next to each: your local .dev_properties.json wins, shared package.json values sit underneath, and in a workspace the root config underneath that. Environments add on top of the base and override only what differs.',
+            'Enter edits and saves a field, Esc cancels, ←→ or space cycles choices, Ctrl+O lists the addons on the site. y copies shared values into package.json for the team.',
+            'Passwords and secrets go to the OS keychain, never to a file. Leave them empty to be asked on each run.',
+        ],
+    },
+    versions: {
+        title: 'Versions',
+        text: [
+            "The versions uploaded to the addon on the active environment's site, the domain in the top bar. v switches environment.",
+            '↑↓ select, a activates the selected version, r refreshes. Production deploys activate on their own.',
+        ],
+    },
+    log: {
+        title: 'Log',
+        text: [
+            'Output from build, sign, deploy, dev and watch for the selected app. Dev and watch keep running while you switch apps; K stops them.',
+            '↑↓ scroll, PgUp/PgDn page, f jumps to the end, x toggles line wrap.',
+        ],
+    },
+};
 const MOVE = [
     ['Tab', 'switch pane'],
     ['1–4', 'tabs'],
@@ -15,17 +62,34 @@ const MOVE = [
 function Row({ keys, label }) {
     return (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { bold: true, color: ACCENT, children: keys.padEnd(6) }), label] }));
 }
-export function HelpPanel({ here, height, onClose, }) {
+export function HelpPanel({ here, where, height, onClose, }) {
+    const inner = useRef(null);
+    const [top, setTop] = useState(0);
+    const [total, setTotal] = useState(0);
+    useEffect(() => {
+        if (inner.current)
+            setTotal(measureElement(inner.current).height);
+    });
+    const visible = Math.max(1, height - 1);
+    const max = Math.max(0, total - visible);
     useInput((input, key) => {
         if (key.escape || key.return || input === '?' || input === 'q')
             onClose();
+        else if (key.upArrow)
+            setTop(n => Math.max(0, n - 1));
+        else if (key.downArrow)
+            setTop(n => Math.min(max, n + 1));
+        else if (key.pageUp)
+            setTop(n => Math.max(0, n - visible));
+        else if (key.pageDown)
+            setTop(n => Math.min(max, n + visible));
     });
     // Only keys not already listed elsewhere, e.g. f and x on the Log tab.
     const local = here.filter(hint => actions.every(action => action.key !== hint.key) &&
         MOVE.every(([keys]) => keys !== hint.key));
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, height: height, overflow: "hidden", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, children: t('Keys') }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", t('Esc close')] })] }), _jsxs(Box, { flexWrap: "wrap", columnGap: 4, children: [_jsx(Box, { flexDirection: "column", marginTop: 1, children: GROUPS.map(group => (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: t(group.label) }), actions.flatMap(action => action.group === group.id && action.key
-                                    ? [
-                                        _jsx(Row, { keys: action.key, label: t(action.label) }, action.id),
-                                    ]
-                                    : [])] }, group.id))) }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [local.length > 0 && (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Text, { bold: true, dimColor: true, children: t('Here') }), local.map(hint => (_jsx(Row, { keys: hint.key, label: hint.label }, hint.key + hint.label)))] })), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: t('Move around') }), MOVE.map(([keys, label]) => (_jsx(Row, { keys: keys, label: t(label) }, keys + label)))] })] })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, height: height, overflow: "hidden", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, children: t(GUIDE[where].title) }), _jsxs(Text, { dimColor: true, children: [' · ', max > 0 ? t('↑↓ scroll · Esc close') : t('Esc close')] })] }), _jsx(Box, { flexDirection: "column", overflow: "hidden", height: visible, children: _jsxs(Box, { ref: inner, flexDirection: "column", flexShrink: 0, marginTop: -top, children: [GUIDE[where].text.map(line => (_jsx(Text, { wrap: "wrap", children: t(line) }, line))), _jsx(Box, { marginTop: 1, children: _jsx(Text, { bold: true, children: t('Keys') }) }), _jsxs(Box, { flexWrap: "wrap", columnGap: 4, children: [_jsx(Box, { flexDirection: "column", children: GROUPS.map(group => (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: t(group.label) }), actions.flatMap(action => action.group === group.id && action.key
+                                                ? [
+                                                    _jsx(Row, { keys: action.key, label: t(action.label) }, action.id),
+                                                ]
+                                                : [])] }, group.id))) }), _jsxs(Box, { flexDirection: "column", children: [local.length > 0 && (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Text, { bold: true, dimColor: true, children: t('Here') }), local.map(hint => (_jsx(Row, { keys: hint.key, label: hint.label }, hint.key + hint.label)))] })), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: t('Move around') }), MOVE.map(([keys, label]) => (_jsx(Row, { keys: keys, label: t(label) }, keys + label)))] })] })] })] }) })] }));
 }

package/dist/shell/Shell.d.ts

@@ -5,6 +5,7 @@ interface Props {
     version: string;
     minimal?: boolean;
     updatedFrom?: string;
+    handover?: (job: () => Promise<void>) => void;
 }
-export declare function Shell({ apps: initialApps, workspaceRoot, version, minimal, updatedFrom, }: Props): import("react").JSX.Element;
+export declare function Shell({ apps: initialApps, workspaceRoot, version, minimal, updatedFrom, handover, }: Props): import("react").JSX.Element;
 export {};