@tenyokjs/devdevian-cli 0.7.0-alpha.1 → 0.7.1-alpha.1

package/README.md

@@ -38,7 +38,7 @@ The default `devdevian` command and `devdevian tui` open an alternate terminal s
 - **N** creates a conversation (a community on the Communities screen); **A** asks a question; **R** replies inside a conversation; **Shift+R** refreshes.
 - **C** comments on snippet lines; **E/D** edit/delete your own ordinary replies or code feedback; **S** resolves/reopens a code remark or accepts/removes a reply as the solution (question/review author only); **!** reports selected code feedback.
 - **Ctrl+E** opens the current multiline field in `$VISUAL` / `$EDITOR` (use `code --wait` for VS Code). Closing the editor restores the form; publishing still requires preview and confirmation. **Ctrl+L** saves an active draft and returns to sign-in.
-- In forms, **Tab/Shift+Tab** change fields, arrows choose options or move the text cursor, **Enter** adds a line, **Ctrl+S** opens the preview. Publication requires a separate confirmation; Escape asks before discarding a draft. Drafts auto-save locally after a short pause and can be restored from **Local drafts** or `/drafts`.
+- In forms, **Tab/Shift+Tab** change fields or focus the step controls, arrows choose options or move the text cursor, **Enter** adds a line inside multiline text, and **Ctrl+S** opens the preview. Publication requires a separate confirmation; Escape asks before discarding a draft. Drafts auto-save locally after a short pause and can be restored from **Local drafts** or `/drafts`.
 - **Ctrl+C** exits. With an unsent draft, confirm saving and leaving or press Ctrl+C again to force exit.
 
 `devdevian open` launches Terminal on macOS, Windows Terminal on Windows, or GNOME Terminal/Konsole/xterm on a Linux desktop. A graphical desktop and an installed supported terminal are required; over SSH and inside an editor, use `devdevian tui`. Window launchers still need platform-specific user testing; terminal rendering and input are covered by macOS/Linux pseudo-terminal checks.
@@ -63,10 +63,12 @@ Forms autosave locally. Successful upload IDs are retained if validation fails;
 
 Press **Ctrl+K** outside a form or command input, or run **/actions**, to search actions, sections and creation flows. Recent views stay in memory for the current account/session; the palette offers up to eight. Type `project 7`, `event 9` or `open 142` for an explicit ID, or choose the forum-search result for a text query. Typing stays local; actions run only after Enter. Destructive actions retain their separate confirmation. **Esc** returns to the previous view without moving your selection.
 
-Conversation, Project and Event forms show one step at a time. **Ctrl+N** validates the current step and moves forward; **Ctrl+P** returns to the previous step. **Tab** still moves through all fields and crosses steps. **Ctrl+S** checks every required field and opens the full publication preview; a missing value returns you to its step. Step changes preserve text, image paths, code selections and locally saved drafts. No upload or publication happens just by advancing a step.
+Conversation, Project and Event forms show one step at a time. **Ctrl+N** validates the current step and moves forward; **Ctrl+P** returns to the previous step. **Tab / Shift+Tab** move through the current step and its **Back / Next** controls. Use arrows to choose a control and **Enter** to activate it; the last step offers **Preview**, not immediate publication. **Ctrl+S** checks every required field and opens the full publication preview; a missing value returns you to its step. Step changes preserve text, image paths, code selections and locally saved drafts. No upload or publication happens just by advancing a step.
 
 In full-text reading (**Space** on a reply or remark), **/** opens local text search. **Enter** locates a matching rendered line; **n / Shift+N** cycles forward/backward. **Home / End** jumps to the start/end. **Esc** returns to the underlying view, and reopening the same unchanged item restores your place. This is bounded session memory, not cross-device or permanent reading history. In text fields and the command bar, **Ctrl+K** continues to delete to the end of the line.
 
+Active fields explain their input: Space stays a space, Enter adds a line in multiline fields, and Tab leaves the field. Project feedback accepts text and URLs; dedicated website/repository/additional links are in **People & links**. Additional links use one `Label | https://example.com` per line. Context hints stay below the editor on larger terminals and use the status/hint lines on compact ones. **Ctrl+S** checks the complete form and opens a preview; drafts autosave locally and publication still requires explicit confirmation.
+
 ## Meet Devi
 
 Devi is the Devdevian mascot: a small ghost with a laptop and an orbit. The terminal uses colored ASCII art, so it needs no image protocol or image downloads. A compact drawing is used when space is limited; authentication codes, addresses and controls take priority over decoration.

package/VERSIONS.md

@@ -8,6 +8,14 @@ Every published npm artifact has a unique immutable version. We record each vers
 
 **0.7.0 focuses on everyday terminal use**: discoverable quick actions, staged forms and resumable reading.
 
+## 0.7.1-alpha.1 — Clearer forms
+
+- Added visible, keyboard-focusable Back / Next controls to staged forms. Tab reaches the controls at step boundaries, arrows choose an available action and Enter activates it. The final action is Preview; publication remains a separate confirmation. Ctrl+N/P shortcuts remain available.
+- Pinned input guidance distinguishes Space, multiline Enter, field navigation and image/code pickers. Project help explicitly points to the dedicated People & links step. Compact layouts prioritize the caret and keep guidance in status/hint lines.
+- Clarified additional-link syntax, preview versus autosaved drafts, and optional URL fields. Opening a new form clears stale success notices.
+- Regression coverage publishes a project through the real terminal and isolated API, checks text spaces/newlines and multiple labeled links from a second account, exercises Back/Next/Preview, preserves Git/image selections and checks multiline editing at 60×18.
+- No API/schema change, new dependency or production-data reset. Per-version history is recorded here; no separate GitHub release is required for this patch.
+
 ## 0.7.0-alpha.1 — Everyday flow
 
 - Added a searchable quick-action workspace via `Ctrl+K` or `/actions`: scoped actions, navigation, creation, up to eight recent views, explicit ID opening and a regular forum-search fallback. Typing performs no requests or mutations; existing server permissions and confirmation dialogs still apply.

package/bin/devdevian.mjs

@@ -117,6 +117,7 @@ const help = `Devdevian CLI ${version} · alpha
   Inside the workspace: /projects, /project ID, /events, /event ID
   Ctrl+K or /actions opens quick actions; type to filter
   Ctrl+N / Ctrl+P moves between form steps; Ctrl+S validates and previews
+  Forms: Tab fields/buttons, Enter selects Back/Next or adds a line in multiline text
   Full reply text: / find, n/N matches, Home/End, Esc remembers your place
   N creates · F filters · E edits your publication · X opens context actions
 

package/lib/form-guidance.mjs

@@ -0,0 +1,38 @@
+export function fieldGuidance(field, { wizard = false, project = false } = {}) {
+  if (!field)
+    return {
+      detail: "",
+      keys: wizard
+        ? "Enter selects the highlighted action"
+        : "Enter opens the preview",
+    };
+  let detail = field.hint || "";
+  if (project && field.key === "help")
+    detail =
+      "Text and links are allowed. Dedicated links: People & links step.";
+  if (["url", "repo", "demo_url"].includes(field.key) && !detail)
+    detail = "Use a complete https:// or http:// URL.";
+  if (["logo", "banner"].includes(field.key))
+    return { detail, keys: "Ctrl+O selects an image · Tab next field" };
+  if (field.key === "file")
+    return { detail, keys: "Ctrl+O file · Ctrl+G Git diff · Tab next field" };
+  const keys = field.options
+    ? "← / → choose · Tab next field"
+    : field.multiline
+      ? "Space inserts a space · Enter adds a line · Tab next field"
+      : "Space inserts a space · Enter / Tab next field";
+  return { detail, keys };
+}
+export function stepControls(steps, index) {
+  return [
+    { id: "back", label: "← Back", enabled: index > 0 },
+    {
+      id: "next",
+      label:
+        index === steps.length - 1
+          ? "Preview →"
+          : "Next: " + steps[index + 1]?.label + " →",
+      enabled: true,
+    },
+  ];
+}

package/lib/tui.mjs

@@ -43,6 +43,7 @@ import {
   appearanceFlags,
 } from "./appearance.mjs";
 import { liveLoop, anchoredIndex } from "./live.mjs";
+import { fieldGuidance, stepControls } from "./form-guidance.mjs";
 import { paletteItems } from "./palette.mjs";
 import {
   formSteps,
@@ -289,21 +290,29 @@ function InputText({ value, cursor, width, height = 1 }) {
     }),
   );
 }
-function FormView({ form, active, cursor, width, height }) {
+function FormView({ form, active, cursor, width, height, navFocus }) {
   const colors = useTheme();
   const fields = fieldsFor(form),
     rows = [];
   const steps = formSteps(form, fields),
     stepIndex = stepAt(steps, active, fields.length),
     step = steps[stepIndex];
+  const guidance = fieldGuidance(navFocus ? null : fields[active], {
+    wizard: !!step,
+    project: form.kind === "catalog" && form.entity === "project",
+  });
+  const helpRows =
+      form.kind === "appearance" ? 0 : height >= 8 ? 2 : height >= 5 ? 1 : 0,
+    navRows = step && height >= 3 ? 1 : 0;
+  const editorHeight = Math.max(1, height - helpRows - navRows);
   let selectedLine = rows.length;
   fields.forEach((field, index) => {
     if (step && !step.indexes.includes(index)) return;
     if (index === active) selectedLine = rows.length;
     rows.push({
-      text: (index === active ? "› " : "  ") + field.label,
-      color: index === active ? colors.purple : colors.muted,
-      bold: index === active,
+      text: (index === active && !navFocus ? "› " : "  ") + field.label,
+      color: index === active && !navFocus ? colors.purple : colors.muted,
+      bold: index === active && !navFocus,
     });
     if (field.options) {
       const option = field.options.find(
@@ -312,12 +321,12 @@ function FormView({ form, active, cursor, width, height }) {
       rows.push({
         text:
           "  ‹ " + (option?.[1] || form.values[field.key] || "Choose") + " ›",
-        color: index === active ? colors.blue : colors.text,
+        color: index === active && !navFocus ? colors.blue : colors.text,
       });
     } else {
       const value = form.values[field.key] || "";
       const text =
-        index === active
+        index === active && !navFocus
           ? cursorLines(value, cursor, width - 3).lines
           : wrap(value || "…", width - 3);
       const caretLine =
@@ -329,7 +338,9 @@ function FormView({ form, active, cursor, width, height }) {
           : 0;
       const visible = field.multiline
           ? Math.min(
-              index === active ? Math.max(1, Math.min(12, height - 3)) : 3,
+              index === active
+                ? Math.max(1, Math.min(12, editorHeight - 2))
+                : 3,
               Math.max(2, text.length),
             )
           : 1,
@@ -337,16 +348,14 @@ function FormView({ form, active, cursor, width, height }) {
       rows.push(
         ...text.slice(start, start + visible).map((line) => ({
           text: "  " + line,
-          color: index === active ? colors.text : colors.muted,
+          color: index === active && !navFocus ? colors.text : colors.muted,
         })),
       );
     }
-    if (field.hint && active === index)
-      rows.push({ text: "  " + field.hint, color: colors.muted });
     rows.push("");
   });
   if (active === fields.length) selectedLine = rows.length;
-  if (!step || stepIndex === steps.length - 1)
+  if (!step)
     rows.push({
       text:
         (active === fields.length ? "› " : "  ") +
@@ -362,9 +371,56 @@ function FormView({ form, active, cursor, width, height }) {
     });
   const offset = Math.max(
     0,
-    Math.min(selectedLine - (height >= 4 ? 1 : 0), rows.length - height),
+    Math.min(
+      selectedLine - (editorHeight >= 4 ? 1 : 0),
+      rows.length - editorHeight,
+    ),
+  );
+  return h(
+    Box,
+    { flexDirection: "column", height, overflow: "hidden" },
+    h(FrameRows, { rows, width, height: editorHeight, offset }),
+    helpRows === 2
+      ? h(TextLine, {
+          text:
+            guidance.detail ||
+            (form.kind === "catalogFilter"
+              ? "Ctrl+S applies these filters."
+              : form.kind === "calendar"
+                ? "Ctrl+S exports a new calendar file."
+                : "Ctrl+S opens a preview; publishing requires separate confirmation."),
+          width,
+          color: colors.muted,
+        })
+      : null,
+    helpRows
+      ? h(TextLine, { text: guidance.keys, width, color: colors.muted })
+      : null,
+    navRows
+      ? h(
+          Text,
+          { wrap: "truncate" },
+          ...stepControls(steps, stepIndex).map((control) =>
+            h(
+              Text,
+              {
+                key: control.id,
+                color: !control.enabled
+                  ? colors.muted
+                  : navFocus === control.id
+                    ? colors.blue
+                    : colors.purple,
+                bold: navFocus === control.id,
+                dimColor: !control.enabled,
+                backgroundColor:
+                  navFocus === control.id ? colors.selected : undefined,
+              },
+              ` ${navFocus === control.id ? "›" : " "}[ ${control.label} ] `,
+            ),
+          ),
+        )
+      : null,
   );
-  return h(FrameRows, { rows, width, height, offset });
 }
 function listRows(route, data, index, width, colors, density = "comfortable") {
   const items = data.items || [];
@@ -591,6 +647,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
     [notice, setNotice] = useState(initialAppearance.warning || "");
   const [form, setForm] = useState(null),
     [field, setField] = useState(0),
+    [formNav, setFormNav] = useState(null),
     [cursor, setCursor] = useState(0),
     [preview, setPreview] = useState(null),
     [dialog, setDialog] = useState(null),
@@ -893,6 +950,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
     setReaderFind({ query: "", cursor: 0, editing: false });
   }
   function moveStep(direction) {
+    setFormNav(null);
     const fields = fieldsFor(form),
       steps = formSteps(form, fields),
       currentStep = stepAt(steps, field, fields.length);
@@ -1392,6 +1450,8 @@ function App({ initialConfig, flags, root, initialAppearance }) {
     );
   }
   function openForm(next) {
+    setFormNav(null);
+    setNotice("");
     setBooting(false);
     setForm({
       ...next,
@@ -1556,6 +1616,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
   }
   async function prepare() {
     if (!form) return;
+    setFormNav(null);
     if (form.kind === "catalogFilter") {
       await task(async () => {
         const values = validateFilter(form.values);
@@ -2128,7 +2189,19 @@ function App({ initialConfig, flags, root, initialAppearance }) {
   }
   function changeField(next) {
     const fields = fieldsFor(form),
-      selected = (next + fields.length + 1) % (fields.length + 1);
+      steps = formSteps(form, fields),
+      stepIndex = stepAt(steps, field, fields.length),
+      step = steps[stepIndex];
+    if (
+      step &&
+      !formNav &&
+      ((next > field && field === step.indexes.at(-1)) ||
+        (next < field && field === step.indexes[0]))
+    ) {
+      setFormNav(next < field && stepIndex > 0 ? "back" : "next");
+      return;
+    }
+    const selected = (next + fields.length + 1) % (fields.length + 1);
     setField(selected);
     setCursor(
       selected < fields.length
@@ -2324,7 +2397,12 @@ function App({ initialConfig, flags, root, initialAppearance }) {
       return;
     }
     if (form) {
-      if (keyEvent.ctrl && input === "o" && form.kind === "catalog") {
+      if (
+        keyEvent.ctrl &&
+        input === "o" &&
+        form.kind === "catalog" &&
+        !formNav
+      ) {
         const active = fieldsFor(form)[field];
         if (["logo", "banner", "screenshots"].includes(active?.key)) {
           setPicker({ mediaKey: active.key });
@@ -2359,7 +2437,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
         moveStep(input === "n" ? 1 : -1);
         return;
       }
-      if (keyEvent.ctrl && input === "e") {
+      if (keyEvent.ctrl && input === "e" && !formNav) {
         externalEdit();
         return;
       }
@@ -2367,6 +2445,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
         keyEvent.ctrl &&
         ["o", "g"].includes(input) &&
         form.kind === "publication" &&
+        !formNav &&
         form.values.kind === "review"
       ) {
         setPicker(input === "g" ? "changes" : "files");
@@ -2390,6 +2469,39 @@ function App({ initialConfig, flags, root, initialAppearance }) {
         prepare();
         return;
       }
+      if (formNav) {
+        const fields = fieldsFor(form),
+          steps = formSteps(form, fields),
+          i = stepAt(steps, field, fields.length),
+          step = steps[i];
+        if (keyEvent.return) {
+          moveStep(formNav === "back" ? -1 : 1);
+          return;
+        }
+        if (keyEvent.leftArrow || keyEvent.upArrow) {
+          setFormNav(i > 0 ? "back" : "next");
+          return;
+        }
+        if (keyEvent.rightArrow || keyEvent.downArrow) {
+          setFormNav("next");
+          return;
+        }
+        if (keyEvent.tab) {
+          if (keyEvent.shift && formNav === "next" && i > 0) {
+            setFormNav("back");
+            return;
+          }
+          if (!keyEvent.shift && formNav === "back") {
+            setFormNav("next");
+            return;
+          }
+          const next = keyEvent.shift ? step.indexes.at(-1) : step.indexes[0];
+          setFormNav(null);
+          setField(next);
+          setCursor(graphemes(form.values[fields[next].key] || "").length);
+        }
+        return;
+      }
       if (keyEvent.tab) {
         changeField(field + (keyEvent.shift ? -1 : 1));
         return;
@@ -2735,8 +2847,16 @@ function App({ initialConfig, flags, root, initialAppearance }) {
       reportSelected();
     }
   });
+  const compactFieldHelp =
+    form && !formNav && form.kind !== "appearance" && contentHeight < 8
+      ? fieldGuidance(fieldsFor(form)[field], {
+          wizard: !!activeSteps.length,
+          project: form.kind === "catalog" && form.entity === "project",
+        }).detail
+      : "";
   const status =
     error ||
+    compactFieldHelp ||
     liveStatus ||
     notice ||
     (pending
@@ -3087,6 +3207,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
       body = h(form.kind === "appearance" ? AppearanceView : FormView, {
         form,
         active: field,
+        navFocus: formNav,
         cursor,
         width: contentWidth,
         height: contentHeight,
@@ -3432,7 +3553,11 @@ function App({ initialConfig, flags, root, initialAppearance }) {
                   : preview
                     ? "← → choose · Enter confirm · Esc edit"
                     : form
-                      ? "Tab field · Ctrl+N/P steps · Ctrl+E editor · Ctrl+S preview"
+                      ? formNav
+                        ? `${stepControls(activeSteps, activeStep).find((control) => control.id === formNav)?.label || "Next"} · Enter select · Tab fields · Ctrl+S preview`
+                        : fieldsFor(form)[field]?.multiline
+                          ? "Enter new line · Tab next field · Ctrl+N next step · Ctrl+S preview"
+                          : "Enter/Tab next field · Ctrl+N/P steps · Ctrl+S preview"
                       : phase !== "ready"
                         ? "Enter connect / open browser · Ctrl+C exit"
                         : route.view === "feedback"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenyokjs/devdevian-cli",
-  "version": "0.7.0-alpha.1",
+  "version": "0.7.1-alpha.1",
   "description": "Devdevian in your terminal: discussions, questions and human code reviews.",
   "type": "module",
   "bin": {