walover-line-harness-gui 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "walover-line-harness-gui",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "LINE Harness のセットアップを、ターミナルを開かずにブラウザから行うためのローカルツール",
   "license": "MIT",
   "type": "module",

package/src/server/cli-version.js

@@ -6,8 +6,12 @@
  * そのため**動作確認済みの版を固定して呼ぶ**。
  *
  * ただし固定したまま黙っていると、本家の修正に永久に追いつかない。
- * 起動時に npm の `latest` と比べ、差があれば**警告だけ**出す。
- * 自動では追従しない。追従には契約の再照合（`npm run check:contract`）が要る。
+ * 起動時に npm の `latest` と比べ、差があれば知らせる。自動では追従しない。
+ * 追従には契約の再照合（`npm run check:contract`）が要る。
+ *
+ * **強さを取り違えない。** 新しい版が出ているだけなら参加者はこのまま進めてよく、
+ * 警告として出すと進めてよいのに手が止まる。一方、固定版が npm で見つからないのは
+ * 人が確かめる必要がある。この区別を {@link VersionNotice} の tone で表す。
  *
  * > npm パッケージ（`create-line-harness`）とアプリ本体（`line-oss-crm`）は
  * > バージョンが別で、プロンプトは npm パッケージ側にある。
@@ -64,7 +68,23 @@ export async function resolveVersion(spec = "latest", options = {}) {
  * @property {string} pinned                     固定している版
  * @property {string|null} latest                npm の最新版。取れなければ null
  * @property {"pinned-is-latest"|"newer-available"|"pinned-is-newer"|"unknown"} status
- * @property {string|null} warning               画面に出す文言
+ * @property {VersionNotice|null} notice         画面に出すもの
+ * @property {string|null} warning               ターミナルに出す平文（notice から作る）
+ */
+
+/**
+ * 画面に出すときの中身。
+ *
+ * **読者は非開発者の勉強会参加者。** 版が古いこと自体は参加者の関心事ではなく、
+ * 知りたいのは「自分はこのまま進めてよいのか」だけ。
+ * headline はその答えを先に書き、版番号のような事情は detail に送る。
+ *
+ * tone は強さ。`info` は畳んで出してよいもの、`warn` は人の判断が要るもの。
+ *
+ * @typedef {object} VersionNotice
+ * @property {"info"|"warn"} tone
+ * @property {string} headline   参加者が最初に読む一文
+ * @property {string} detail     事情の説明。畳んだ中に置く
  */
 
 /**
@@ -84,6 +104,7 @@ export async function checkCliVersion(options = {}) {
       pinned,
       latest: null,
       status: "unknown",
+      notice: null,
       warning: null,
     };
   }
@@ -91,31 +112,45 @@ export async function checkCliVersion(options = {}) {
   const order = compareVersions(pinned, latest);
 
   if (order === 0) {
-    return { pinned, latest, status: "pinned-is-latest", warning: null };
+    return { pinned, latest, status: "pinned-is-latest", notice: null, warning: null };
   }
 
   if (order < 0) {
-    return {
+    // 新しい版が出ているだけ。**参加者はこのまま進めてよい。**
+    // ここを警告として強く出すと、進めてよいのに手が止まる
+    return withWarning({
       pinned,
       latest,
       status: "newer-available",
-      warning: [
-        `本家 CLI の新しい版 v${latest} が出ています（このツールが確認済みなのは v${pinned}）。`,
-        "動作未確認のため、追従には検証が必要です。このままでも v" + pinned + " でセットアップできます。",
-      ].join("\n"),
-    };
+      notice: {
+        tone: "info",
+        headline: `このまま進めて構いません。動作確認済みの v${pinned} でセットアップします。`,
+        detail:
+          `本家 CLI の新しい版 v${latest} が出ています（このツールが確認済みなのは v${pinned}）。` +
+          "追従にはプロンプト契約の再照合と検証が要るため、自動では追いかけません。",
+      },
+    });
   }
 
-  // 固定版のほうが新しい。npm 側が取り下げられた場合などに起きる
-  return {
+  // 固定版のほうが新しい。npm 側が取り下げられた場合などに起きる。
+  // これは**人が確かめる必要がある**ので、弱めない
+  return withWarning({
     pinned,
     latest,
     status: "pinned-is-newer",
-    warning: [
-      `固定している v${pinned} が npm の最新 v${latest} より新しくなっています。`,
-      "npm 側で取り下げられた可能性があります。動作未確認のため、確認が必要です。",
-    ].join("\n"),
-  };
+    notice: {
+      tone: "warn",
+      headline: "固定している版が npm で見つかりません。開発者に連絡してください。",
+      detail:
+        `固定している v${pinned} が npm の最新 v${latest} より新しくなっています。` +
+        "npm 側で取り下げられた可能性があります。動作未確認のため、確認が必要です。",
+    },
+  });
+}
+
+/** ターミナル用の平文。画面と同じ内容を1つの文字列にする */
+function withWarning(status) {
+  return { ...status, warning: `${status.notice.headline}\n${status.notice.detail}` };
 }
 
 /** @type {Promise<VersionStatus>|null} */

package/src/server/guide.js

@@ -33,6 +33,27 @@ const CF_R2 = "https://dash.cloudflare.com/?to=/:account/r2/overview";
  * @property {{url: string, label: string}} [manual]   手順書の該当箇所
  */
 
+/**
+ * R2 の有効化。
+ *
+ * 実測で**最初のブロッカーであり、最大の脱落ポイント**だった箇所。
+ * 始める前の前提条件（{@link PREFLIGHT}）としても、本家が実行中に訊いてくる
+ * `r2Enabled` の場面でも、同じものを見せる。
+ *
+ * @type {Guide}
+ */
+const R2_GUIDE = {
+  steps: [
+    "Cloudflare にログインする",
+    "支払い情報（クレジットカード）を登録する",
+    "R2 の画面で「Purchase R2」などのボタンを押し、利用を開始する",
+    "もう一度 R2 の画面を開き、バケットの一覧（空でよい）が出ることを確かめる",
+  ],
+  warn: "「カード登録済み」と「R2 有効化済み」は別です。カードを登録しただけで進むと、あとの手順で必ず失敗します（実測でも、カード登録済みのアカウントが code: 10042 で止まりました）。",
+  links: [{ label: "Cloudflare の R2 を開く", url: CF_R2 }],
+  manual: { url: `${KIT}/cloudflare.html#step3`, label: "1. Cloudflare の準備 — Step 3：R2 を有効化する" },
+};
+
 /**
  * プロンプト id をキーにする。フォームの欄も、実行中に人が答える場面も同じ扱いにできる。
  * @type {Record<string, Guide>}
@@ -154,16 +175,7 @@ export const GUIDE = {
   },
 
   // ── 実行中に人が答える場面 ───────────────────────────────────────
-  r2Enabled: {
-    steps: [
-      "Cloudflare ダッシュボードの R2 を開く",
-      "支払い情報（クレジットカード）を登録する",
-      "R2 の利用を開始する",
-    ],
-    warn: "「カード登録済み」と「R2 有効化済み」は別です。カードを登録しただけで進むと、あとの手順で必ず失敗します。",
-    links: [{ label: "Cloudflare の R2 を開く", url: CF_R2 }],
-    manual: { url: `${KIT}/cloudflare.html`, label: "1. Cloudflare の準備" },
-  },
+  r2Enabled: R2_GUIDE,
 
   subdomainManualCheck: {
     steps: [
@@ -175,6 +187,38 @@ export const GUIDE = {
   },
 };
 
+/**
+ * 始める前に済ませておくこと。
+ *
+ * R2 の有効化は、本家が実行の途中で「R2 の有効化は終わりましたか？」と訊く。
+ * だが実機では、**そこで初めて気づいて手が止まる参加者が多かった**。
+ * 有効化には別タブでの作業とクレジットカードの登録が要るので、
+ * 入力を全部済ませたあとに知らされるのでは遅い。
+ *
+ * フォームより前に出し、**開始の前提条件**として扱う。
+ * 実行中の `r2Enabled` の場面は残す（そこで初めて出すのをやめるだけ）。
+ *
+ * @typedef {object} Prerequisite
+ * @property {string} id           対応するプロンプト id
+ * @property {string} title        画面の見出し
+ * @property {string} body         なぜ先にやるのか
+ * @property {string} confirmLabel 参加者に確認させる文
+ * @property {Guide} guide         作業の手順
+ *
+ * @type {Prerequisite[]}
+ */
+export const PREFLIGHT = [
+  {
+    id: "r2Enabled",
+    title: "始める前に：Cloudflare の R2 を有効化してください",
+    body:
+      "R2 は画像などの保管場所です（10GB まで無料）。有効化しないまま始めると、" +
+      "LINE の値をすべて入力し終えたあと、終盤の保管場所づくりで必ず失敗します。",
+    confirmLabel: "R2 を有効化しました（R2 の画面にバケットの一覧が出ています）",
+    guide: R2_GUIDE,
+  },
+];
+
 /** @param {string} promptId */
 export function guideFor(promptId) {
   return GUIDE[promptId] ?? null;

package/src/server/prompt-contract.js

@@ -23,7 +23,7 @@
  */
 
 /** 契約が対象とする本家 CLI のバージョン。ズレの検知は #5 で行う */
-export const CONTRACT_CLI_VERSION = "0.2.11";
+export const CONTRACT_CLI_VERSION = "0.2.12";
 
 /**
  * @typedef {object} PromptSpec
@@ -133,7 +133,9 @@ export const PROMPTS = [
     id: "lineChannelSecret",
     message: "チャネルシークレット（英数字）",
     kind: "text",
-    placeholder: "同じページに表示されている Channel Secret",
+    // 0.2.12 で本家が p.text → p.password にした。値行は伏字（▪）になり、
+    // placeholder は無くなった。宣言したままだと第二の照合が外れて止まる。
+    // message が一意なので、外しても取り違えは起きない
     secret: true,
     answer: "form",
     field: "lineChannelSecret",
@@ -148,7 +150,7 @@ export const PROMPTS = [
     id: "lineChannelAccessToken",
     message: "チャネルアクセストークン（長期）",
     kind: "text",
-    placeholder: "上の手順で発行したトークン",
+    // 同上。0.2.12 で p.password になった
     secret: true,
     answer: "form",
     field: "lineChannelAccessToken",

package/src/server/pty.js

@@ -201,8 +201,15 @@ function resolveLaunch(command, args) {
   if (command !== "npx" && command !== "npm") return { command, args };
 
   // /d = AutoRun をスキップ、/s = 引用符の扱いを素直にする
+  //
+  // chcp 65001 はコンソールのコードページを UTF-8 にするため。
+  // 日本語環境の既定は CP932 で、本家が出す日本語がそのままだと文字化けする
+  // （勉強会の実機で確認）。
   const shell = process.env.ComSpec || "cmd.exe";
-  return { command: shell, args: ["/d", "/s", "/c", command, ...args] };
+  return {
+    command: shell,
+    args: ["/d", "/s", "/c", `chcp 65001 >nul && ${[command, ...args].join(" ")}`],
+  };
 }
 
 /**

package/src/server/state.js

@@ -19,7 +19,7 @@ import {
   validateAnswer,
   crossCheckAnswers,
 } from "./prompt-contract.js";
-import { guideFor, GUIDE } from "./guide.js";
+import { guideFor, GUIDE, PREFLIGHT } from "./guide.js";
 
 /** @type {{ answers: Record<string, string|boolean>, run: SetupRun|null }} */
 const state = {
@@ -75,10 +75,16 @@ export function filledFields() {
     .map(([k]) => k);
 }
 
-/** #2 のフォームが参照する、入力欄の定義。値は一切含まない */
+/**
+ * #2 のフォームが参照する、入力欄の定義と**始める前の前提条件**。値は一切含まない。
+ *
+ * 前提条件をここに載せるのは、画面がフォームを組み立てる前に読む唯一の定義だから。
+ * R2 の有効化は、入力を始める前に見えていないと意味がない。
+ */
 export function formSchema() {
   return {
     cliVersion: CONTRACT_CLI_VERSION,
+    prerequisites: PREFLIGHT,
     groups: FORM_GROUPS,
     fields: FORM_FIELDS.map((f) => {
       const spec = PROMPTS.find((p) => p.id === f.promptId);

package/src/web/index.html

@@ -63,12 +63,41 @@
   .banner.bad { border-color: var(--err-line); background: var(--err-bg); color: var(--err); }
   .banner strong { display: block; }
 
+  /*
+   * 版のズレのように「知らせるが、進めてよい」もの。
+   * 警告（.banner）と同じ強さで出すと、進めてよいのに手が止まる
+   */
+  .note { font-size: .85rem; color: var(--muted); margin: 0 0 1rem; }
+  .note > summary { cursor: pointer; list-style-position: inside; }
+  .note > summary::marker { color: var(--muted); }
+  .note .note-detail { margin: .4rem 0 0 1.1rem; padding-left: .7rem;
+                       border-left: 2px solid var(--line); white-space: pre-line; }
+
   .status { display: flex; align-items: center; gap: .5rem; font-size: .85rem; color: var(--muted);
             margin-bottom: 1.5rem; }
   .dot { width: .55rem; height: .55rem; border-radius: 50%; background: var(--muted); flex: none; }
   .dot.ok { background: var(--brand); }
   .dot.bad { background: var(--err); }
 
+  /*
+   * 始める前の前提条件（R2 の有効化）。
+   *
+   * 実機では、有効化しないまま始めてしまう参加者が多かった。フォームより前に、
+   * 見落としようのない形で置く。囲みの上の警告（.banner）と同じ黄色の面だが、
+   * こちらは**開始の条件**なので、枠を太くして見出しを立てる。
+   */
+  .preflight { border: 2px solid var(--warn-line); background: var(--warn-bg);
+               border-radius: .6rem; padding: 1.1rem 1.25rem; margin-bottom: 1.75rem; }
+  .preflight h2 { font-size: 1.05rem; margin: 0 0 .35rem; }
+  .preflight .why { margin: 0 0 .75rem; font-size: .9rem; }
+  .preflight .guide-body { padding: 0; font-size: .88rem; }
+  /* 黄色の面の上で、いちばん効かせたい一文が沈まないようにする */
+  .preflight .guide-warn { background: var(--bg); }
+  .gate { display: flex; align-items: flex-start; gap: .6rem; font-weight: 600; font-size: .92rem;
+          margin-top: .9rem; padding-top: .85rem; border-top: 1px solid var(--warn-line); }
+  .gate input { margin-top: .4rem; flex: none; }
+  .gate-note { font-size: .85rem; color: var(--muted); }
+
   fieldset { border: 1px solid var(--line); border-radius: .6rem; padding: 1.25rem;
              margin: 0 0 1.25rem; border-left-width: 4px; }
   fieldset[data-group="project"] { border-left-color: var(--brand); }
@@ -205,6 +234,8 @@
     <span class="dot" id="dot"></span><span id="status">確認中…</span>
   </div>
 
+  <section id="preflight" hidden></section>
+
   <form id="form" autocomplete="off" novalidate hidden></form>
 
   <section id="run" hidden>
@@ -264,10 +295,21 @@
     );
   }
 
-  // 本家 CLI の版のズレ（固定版で動かすので、差があっても止めずに知らせるだけ）
+  // 本家 CLI の版のズレ。
+  //
+  // 固定版で動かすので、新しい版が出ているだけなら**参加者はこのまま進めてよい**。
+  // そこを警告として強く出すと、進めてよいのに手が止まる（実機で起きた）。
+  // 強さはサーバーが tone で決める。ここはそれに従って出し分けるだけ
   try {
     const version = await (await fetch("/api/version")).json();
-    if (version.warning) banner("本家 CLI のバージョン", version.warning);
+    if (version.notice?.tone === "warn") {
+      banner(version.notice.headline, version.notice.detail, true);
+    } else if (version.notice) {
+      const box = el("details", { className: "note" });
+      box.append(el("summary", { textContent: version.notice.headline }));
+      box.append(el("p", { className: "note-detail", textContent: version.notice.detail }));
+      $("banners").append(box);
+    }
   } catch {
     /* 版が確認できなくても入力は進められる */
   }
@@ -297,6 +339,37 @@
   const form = $("form");
   const inputs = new Map();
 
+  /**
+   * 始める前に済ませておくこと（R2 の有効化）。
+   *
+   * 実機では、有効化しないまま始めてしまう参加者が多かった。本家がそれを訊くのは
+   * 実行の途中で、そこまで来て初めて気づくと手が止まる。**フォームより前**に出し、
+   * 確認するまで「セットアップを開始する」を押せなくする。
+   */
+  const gates = [];
+  for (const item of schema.prerequisites ?? []) {
+    const box = el("div", { className: "preflight" });
+    box.append(el("h2", { textContent: item.title }));
+    if (item.body) box.append(el("p", { className: "why", textContent: item.body }));
+    // ここは畳まない。開かないと読めない形では、素通りされる
+    if (item.guide) box.append(guideBody(item.guide));
+
+    const check = el("input", { type: "checkbox", id: `gate-${item.id}` });
+    check.addEventListener("change", syncGate);
+    gates.push(check);
+    box.append(
+      el("div", { className: "gate" }, [
+        check,
+        el("label", { htmlFor: `gate-${item.id}`, textContent: item.confirmLabel }),
+      ]),
+    );
+    $("preflight").append(box);
+  }
+  $("preflight").hidden = gates.length === 0;
+
+  /** 前提がすべて確認済みか */
+  const gateReady = () => gates.every((g) => g.checked);
+
   for (const group of schema.groups) {
     const fields = schema.fields.filter((f) => f.group === group.id);
     if (fields.length === 0) continue;
@@ -385,7 +458,17 @@
     const box = el("details", { className: "guide" });
     if (open) box.open = true;
     box.append(el("summary", { textContent: "どこで取るか" }));
+    box.append(guideBody(guide, box));
+    return box;
+  }
 
+  /**
+   * 案内の中身。畳んだ中にも、前提条件のように畳まずに出す場所にも使う。
+   *
+   * @param guide  案内
+   * @param details 畳んで出す場合、その details。画像はそのとき初めて読む
+   */
+  function guideBody(guide, details = null) {
     const body = el("div", { className: "guide-body" });
 
     if (guide.steps?.length) {
@@ -409,21 +492,21 @@
     }
 
     if (guide.images?.length) {
-      // 開いたときに初めて読みにいく。畳まれたままなら要求も出さない
       const slot = el("div");
-      box.addEventListener(
-        "toggle",
-        () => {
-          if (!box.open) return;
-          for (const image of guide.images) {
-            const img = el("img", { src: image.url, alt: image.alt });
-            // ネットワークが無いと読めない。読めなくても手順は残す
-            img.addEventListener("error", () => img.remove());
-            slot.append(img);
-          }
-        },
-        { once: true },
-      );
+      const load = () => {
+        for (const image of guide.images) {
+          const img = el("img", { src: image.url, alt: image.alt });
+          // ネットワークが無いと読めない。読めなくても手順は残す
+          img.addEventListener("error", () => img.remove());
+          slot.append(img);
+        }
+      };
+      // 畳んで出すなら、開いたときに初めて読みにいく。畳まれたままなら要求も出さない
+      if (details && !details.open) {
+        details.addEventListener("toggle", () => details.open && load(), { once: true });
+      } else {
+        load();
+      }
       body.append(slot);
     }
 
@@ -436,8 +519,7 @@
       );
     }
 
-    box.append(body);
-    return box;
+    return body;
   }
 
   /** サーバーから渡された規則で見る。画面側で独自の規則を作らない */
@@ -477,15 +559,39 @@
   const askBox = $("run-ask");
   const screen = $("run-screen");
   let startButton = null;
+  let gateNote = null;
+  /** 開始を投げている最中。この間にチェックを外されても、押し直せるようにはしない */
+  let starting = false;
 
   function showStart() {
     if (startButton) return;
     startButton = el("button", { className: "primary", type: "button", textContent: "セットアップを開始する" });
     startButton.addEventListener("click", startRun);
-    form.querySelector(".actions").append(startButton);
+    gateNote = el("span", { className: "gate-note" });
+    form.querySelector(".actions").append(startButton, gateNote);
+    syncGate();
+  }
+
+  /** 前提を確認するまで開始させない。押せない理由は、押せないボタンの隣に置く */
+  function syncGate() {
+    if (!startButton || starting) return;
+    const ready = gateReady();
+    startButton.disabled = !ready;
+    gateNote.replaceChildren();
+    if (!ready) {
+      gateNote.append(document.createTextNode("開始するには、"));
+      gateNote.append(el("a", { href: "#preflight", textContent: "ページ上部の前提条件" }));
+      gateNote.append(document.createTextNode("を確認してください。"));
+    }
   }
 
   async function startRun() {
+    // 画面の状態がずれていても、前提が未確認のまま走り出さない
+    if (!gateReady()) {
+      syncGate();
+      return;
+    }
+    starting = true;
     startButton.disabled = true;
     const res = await fetch("/api/run/start", {
       method: "POST",
@@ -495,11 +601,13 @@
     if (!res.ok) {
       result.textContent = (await res.json()).error ?? "開始できませんでした。";
       result.className = "result bad";
-      startButton.disabled = false;
+      starting = false;
+      syncGate();
       return;
     }
     // 入力はサーバーに渡した。ここから先は実行の画面
     for (const input of inputs.values()) input.disabled = true;
+    for (const gate of gates) gate.disabled = true;
     submit.disabled = true;
     runBox.hidden = false;
     runBox.scrollIntoView({ behavior: "smooth", block: "start" });