codex-webapp 0.1.2 → 0.1.4

package/README.ja.md

@@ -28,34 +28,53 @@ Codex は、ターミナルだけで完結するツールから、よりアプ
 
 ## Codex App から始める
 
-Codex App を使っている場合は、次の指示をそのまま貼ってください。Codex が準備確認、dry-run、ローカルUIの起動、smoke test までを進め、成功・失敗を報告する想定です。
+Codex App を使っている場合は、次の指示をそのまま貼ってください。Codex が「npm package を一時実行して、ローカルのWeb画面を起動し、ブラウザで開く」ことを認識しやすいように書いてあります。
 
 ```text
-Please set up Codex WebApp on this machine.
+Codex WebApp をこのPCで起動してください。
 
-Use this npm package:
-codex-webapp
+これは OpenAI 公式ではない、Codex App向けの非公式 companion UI です。
+token、cookie、private repository の中身、顧客データ、内部URLは表示しないでください。
+`.env` や `SECRET`、`KEY`、`TOKEN` を含むterminal出力は、AIにもissueにも貼らないでください。
 
-Please:
-1. Check my Codex version. Codex CLI must be 0.130.0 or newer because this uses `codex remote-control`.
-2. Run the package doctor.
-3. Run start in dry-run mode first.
-4. Start the local browser UI on localhost.
-5. Smoke-test the printed local URL.
+次の順番で進めてください。
 
-Do not print tokens, cookies, private repo contents, customer data, or internal URLs.
-Keep any raw Codex browser server on localhost unless I have a trusted access boundary such as Tailscale or Cloudflare Access.
+1. まず `node -v`、`npm -v`、`npx -v` を確認してください。`npx` が使えない場合は、ここで止まり、Node.js/npm が必要だと説明してください。
+2. `npx -y codex-webapp@latest doctor` を実行して、Codex CLI が 0.130.0 以上で、`codex remote-control` が使えるか確認してください。
+3. `doctor` がエラーを出した場合は、ここで止まり、`start` には進まず、原因と直し方を説明してください。
+4. `npx -y codex-webapp@latest start --dry-run` を実行して、起動予定の内容を確認してください。
+5. 問題なければ `npx -y codex-webapp@latest start` を実行して、ローカルのブラウザUIを起動してください。
+6. 起動できたら、ブラウザで `http://127.0.0.1:8214/` を開くように案内してください。
+7. この terminal window を閉じるとWeb画面は止まること、止めたいときは `Ctrl+C` を押すこと、PCを再起動した後はもう一度 `npx -y codex-webapp@latest start` が必要なことも説明してください。
+
+外出先のPCやスマホから使う場合は、raw UI server をpublic IPへ直接公開せず、Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を使ってください。認証なしのport-forwardingやpublic tunnelは使わないでください。
 ```
 
 実際には、おおむね次のようなコマンドが実行されます。
 
 ```bash
-npx -y codex-webapp doctor
-npx -y codex-webapp start --dry-run
-npx -y codex-webapp start
+npx -y codex-webapp@latest doctor
+npx -y codex-webapp@latest start --dry-run
+npx -y codex-webapp@latest start
 ```
 
-`npx` は、npm に公開されている package を一時的に実行する仕組みです。試すだけなら、この repository を clone したり、手元で新しい project を作ったりする必要はありません。
+`npx` は、npm に公開されている package を一時的に実行する仕組みです。試すだけなら、この repository を clone したり、手元で新しい project を作ったりする必要はありません。READMEでは、常に公開済みの最新パッチを使うため `codex-webapp@latest` を指定しています。
+
+> **秘密情報はユーザー側でも確認してください。** Codexには秘密情報を出さないよう指示していますが、AIへの指示だけで安全が保証されるわけではありません。terminal output、`.env`、error log、issue本文を貼る前に、`SECRET`、`KEY`、`TOKEN`、cookie、顧客名、private URL が含まれていないか必ず見てください。
+
+## 起動中だけ使える、という基本
+
+Codex WebApp はクラウド上に常駐するサービスではありません。あなたのPC上で `npx -y codex-webapp@latest start` が動いている間だけ、ブラウザUIが使えます。
+
+| できごと | 何が起きるか | どうすればよいか |
+| --- | --- | --- |
+| terminal window を閉じた | Web画面は止まります。 | もう一度 `npx -y codex-webapp@latest start` を実行します。 |
+| 起動中のUIを止めたい | terminal上のプロセスを止めます。 | 起動しているterminalで `Ctrl+C` を押してください。 |
+| PCをスリープした | 復帰後に動く場合もありますが、接続が切れることがあります。 | 開けない場合は起動し直してください。 |
+| PCを再起動した | プロセスは残りません。 | 再起動後にもう一度 `start` してください。 |
+| 別のPCやスマホから開きたい | `127.0.0.1` は「このPC自身」を指すため、そのままでは別端末から開けません。 | Tailscale、Cloudflare Access、または同等の安全なアクセス境界を用意してください。 |
+
+まずは同じPCのブラウザで `http://127.0.0.1:8214/` を開けるところまでを確認してください。スマホや外出先PCからの利用は、その次の段階です。認証なしのport-forwardingやpublic tunnelでraw UI serverを公開すると、意図しない第三者にあなたのPC上のCodex操作面を見せる危険があります。
 
 ## ターミナルから始める
 
@@ -127,7 +146,7 @@ Codex WebApp は telemetry、analytics、browser extension、project-operated ph
 | Codex CLI | `codex remote-control` を使うため、`0.130.0` 以上が必要です。 |
 | Node.js | `20` 以上が必要です。 |
 | network binding | デフォルトは `127.0.0.1`。非 loopback host は明示的な opt-in が必要です。 |
-| package channel | npm の `latest` channel から `codex-webapp` を使ってください。現在の release は `0.1.2` です。 |
+| package channel | npm の `latest` channel から `codex-webapp` を使ってください。現在の release は `0.1.4` です。 |
 
 Codex が入っていない、または古い場合は、先に更新してください。
 

package/README.md

@@ -57,6 +57,19 @@ npx -y codex-webapp start
 
 `npx` runs the published npm package temporarily. You do not need to create a project, clone this repository, or install Codex WebApp by hand just to try it.
 
+## It only works while the process is running
+
+Codex WebApp is not a hosted cloud service. The browser UI is available only while `npx -y codex-webapp start` is running on your computer.
+
+| Event | What happens | What to do |
+| --- | --- | --- |
+| You close the terminal window | The browser UI stops. | Run `npx -y codex-webapp start` again. |
+| The computer sleeps | The connection may survive, but it can also break. | Restart the command if the page no longer opens. |
+| The computer restarts | The process is gone. | Run `start` again after rebooting. |
+| You want to open it from a phone or another PC | `127.0.0.1` means “this same computer,” so another device cannot use that URL directly. | Put Tailscale, Cloudflare Access, or an equivalent trusted access boundary in front first. |
+
+Start with the same computer first: run the command, then open `http://127.0.0.1:8214/` in that computer’s browser. Phone and remote access should come after that local check passes.
+
 ## Quick start from a terminal
 
 Use this route if you prefer to control the commands yourself. Codex WebApp requires **Node.js 20 or newer** and **Codex CLI 0.130.0 or newer**.
@@ -127,7 +140,7 @@ Codex WebApp does not include telemetry, analytics, a browser extension, or a pr
 | Codex CLI | `0.130.0` or newer, because `codex remote-control` is required. |
 | Node.js | `20` or newer. |
 | Network binding | `127.0.0.1` by default. Non-loopback hosts require explicit opt-in. |
-| Package channel | `codex-webapp` from the npm `latest` channel. Current release: `0.1.2`. |
+| Package channel | `codex-webapp` from the npm `latest` channel. Current release: `0.1.4`. |
 
 If Codex is missing or too old, update it first.
 

package/docs/codex-app-install.md

@@ -15,24 +15,26 @@ Tailscale, Cloudflare Access, or an equivalent trusted boundary.
 
 ## Paste Prompt
 
-Paste this prompt into Codex App:
+Paste this prompt into Codex App. Japanese is intentional here: it is written for users who may be more comfortable asking Codex App in Japanese.
 
 ```text
-Please verify Codex WebApp on this machine.
-
-Constraints:
-- Treat it as an unofficial companion UI, not an OpenAI-endorsed tool.
-- Do not paste or print tokens, cookies, private repository content, customer data, or internal URLs.
-- Keep any raw Codex browser server or app-server on localhost or behind Tailscale, Cloudflare Access, or an equivalent trusted boundary.
-
-Steps:
-1. Check whether Codex is available and whether `codex remote-control --help` works.
-2. If Codex is older than 0.130.0, explain the update that is needed.
-3. Run `npx codex-webapp doctor`.
-4. Run `npx codex-webapp start --dry-run`.
-5. If a UI server is available, run `npx codex-webapp smoke --url http://127.0.0.1:8214/`.
-6. Use `--browser --screenshot artifacts/codex-webapp.png` only when browser evidence is needed.
-7. Summarize pass/fail status and start a small diagnosis if a step fails.
+Codex WebApp をこのPCで起動してください。
+
+これは OpenAI 公式ではない、Codex App向けの非公式 companion UI です。
+token、cookie、private repository の中身、顧客データ、内部URLは表示しないでください。
+`.env` や `SECRET`、`KEY`、`TOKEN` を含むterminal出力は、AIにもissueにも貼らないでください。
+
+次の順番で進めてください。
+
+1. まず `node -v`、`npm -v`、`npx -v` を確認してください。`npx` が使えない場合は、ここで止まり、Node.js/npm が必要だと説明してください。
+2. `npx -y codex-webapp@latest doctor` を実行して、Codex CLI が 0.130.0 以上で、`codex remote-control` が使えるか確認してください。
+3. `doctor` がエラーを出した場合は、ここで止まり、`start` には進まず、原因と直し方を説明してください。
+4. `npx -y codex-webapp@latest start --dry-run` を実行して、起動予定の内容を確認してください。
+5. 問題なければ `npx -y codex-webapp@latest start` を実行して、ローカルのブラウザUIを起動してください。
+6. 起動できたら、ブラウザで `http://127.0.0.1:8214/` を開くように案内してください。
+7. この terminal window を閉じるとWeb画面は止まること、止めたいときは `Ctrl+C` を押すこと、PCを再起動した後はもう一度 `npx -y codex-webapp@latest start` が必要なことも説明してください。
+
+外出先のPCやスマホから使う場合は、raw UI server をpublic IPへ直接公開せず、Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を使ってください。認証なしのport-forwardingやpublic tunnelは使わないでください。
 ```
 
 The proof we want is not that a developer can type commands. The proof is that

package/docs/i18n/README.ko.md

@@ -80,7 +80,7 @@ npx -y codex-webapp smoke \
 
 이 패키지는 Codex App native marketplace plugin, browser extension, one-click installer, managed hosting service가 아닙니다. Codex App에 프롬프트를 붙여 넣고, Codex가 `npx`로 npm 패키지를 실행하는 방식입니다.
 
-현재 release는 `0.1.2`이며 early, compatibility-first입니다. 현재 `0xcaff/codex-web` commit `585613f5a3a355af5aefc388ca4e31b07a472cda`를 참조하는 Codex 스타일 browser runtime을 실행하고, 그 주변에 설치, 안전, 문서, 검증 evidence 계층을 더합니다.
+현재 release는 `0.1.4`이며 early, compatibility-first입니다. 현재 `0xcaff/codex-web` commit `585613f5a3a355af5aefc388ca4e31b07a472cda`를 참조하는 Codex 스타일 browser runtime을 실행하고, 그 주변에 설치, 안전, 문서, 검증 evidence 계층을 더합니다.
 
 ## Security And Privacy
 

package/docs/i18n/README.zh-CN.md

@@ -80,7 +80,7 @@ npx -y codex-webapp smoke \
 
 这不是 Codex App native marketplace plugin、browser extension、one-click installer 或 managed hosting service。它的使用方式是：把提示词粘贴到 Codex App，让 Codex 通过 `npx` 执行 npm 包。
 
-当前 release 为 `0.1.2`，仍处于 early 阶段，并采用 compatibility-first 方针。它目前运行一个引用 `0xcaff/codex-web` commit `585613f5a3a355af5aefc388ca4e31b07a472cda` 的 Codex 风格 browser runtime，并在其周围增加安装、安全、文档和验证证据层。
+当前 release 为 `0.1.4`，仍处于 early 阶段，并采用 compatibility-first 方针。它目前运行一个引用 `0xcaff/codex-web` commit `585613f5a3a355af5aefc388ca4e31b07a472cda` 的 Codex 风格 browser runtime，并在其周围增加安装、安全、文档和验证证据层。
 
 ## Security And Privacy
 

package/docs/ja-quickstart.md

@@ -24,7 +24,7 @@ codex remote-control --help
 ## 3. friendly doctor を実行
 
 ```bash
-npx codex-webapp doctor
+npx -y codex-webapp doctor
 ```
 
 Codexが古い、または `remote-control` が見つからない場合は、次に打つべきコマンドを表示します。
@@ -32,13 +32,13 @@ Codexが古い、または `remote-control` が見つからない場合は、次
 ## 4. Codex-style Web UI を起動
 
 ```bash
-npx codex-webapp start
+npx -y codex-webapp start
 ```
 
 このコマンドは起動前に確認プロンプトを出します。自動化された信頼済み環境だけで `--yes` を使ってください。
 
 ```bash
-npx codex-webapp start --yes
+npx -y codex-webapp start --yes
 ```
 
 ## 5. ブラウザで表示できるか確認
@@ -46,7 +46,7 @@ npx codex-webapp start --yes
 UIサーバーが起動している状態で、実ブラウザ疎通を確認します。
 
 ```bash
-npx codex-webapp smoke \
+npx -y codex-webapp smoke \
   --url http://127.0.0.1:8214/
 ```
 
@@ -55,7 +55,7 @@ npx codex-webapp smoke \
 スクリーンショットも残したい場合は、Playwrightを使うdeep smokeを実行します。
 
 ```bash
-npx codex-webapp smoke \
+npx -y codex-webapp smoke \
   --browser \
   --url http://127.0.0.1:8214/ \
   --screenshot artifacts/codex-webapp.png

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-webapp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Unofficial. Respectful web app surface, doctor, and safety wrapper for Codex App users.",
   "type": "module",
   "license": "Apache-2.0",

package/src/commands.js

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:net";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 
@@ -17,6 +18,17 @@ import {
 } from "./codexWeb.js";
 
 const BANNER = "Codex WebApp — unofficial OpenAI Codex companion; not endorsed by OpenAI.";
+const DEFAULT_WEB_URL = "http://127.0.0.1:8214/";
+
+function codexAppFlowLines(url = DEFAULT_WEB_URL) {
+  return [
+    "Codex App flow:",
+    "  1. Paste a setup request into the Codex App prompt.",
+    "  2. Codex runs: npx -y codex-webapp start",
+    `  3. When it starts, open: ${url}`,
+    "  4. Keep this terminal window open. Closing it will stop the browser UI.",
+  ];
+}
 
 export function main(argv = process.argv) {
   const command = argv[2] ?? "help";
@@ -97,7 +109,9 @@ export function doctor() {
     "`codex remote-control` is available.",
     `codex-web reference: ${CODEX_WEB_REFERENCE}`,
     "Next:",
-    "  npx codex-webapp start",
+    "  npx -y codex-webapp start",
+    "",
+    ...codexAppFlowLines(),
   ]);
 }
 
@@ -126,12 +140,17 @@ export async function start(args = []) {
       BANNER,
       "Dry run passed.",
       `Would start codex-web: ${plannedWebUrl}`,
+      "",
+      ...codexAppFlowLines(plannedWebUrl),
+      "",
       "Would start:",
       `  npx ${npxArgs.join(" ")}`,
     ]);
     return;
   }
 
+  await assertPortAvailable(options.host, options.port);
+
   if (!options.yes) {
     console.log(BANNER);
     console.log(`About to start codex-web: ${plannedWebUrl}`);
@@ -148,6 +167,9 @@ export async function start(args = []) {
 
   console.log(`Starting codex-web from ${CODEX_WEB_REFERENCE}...`);
   console.log(`Open: ${plannedWebUrl}`);
+  console.log("");
+  for (const line of codexAppFlowLines(plannedWebUrl)) console.log(line);
+  console.log("");
   console.log("Keep this terminal open. Expose it only through a trusted local, Tailscale, Cloudflare Access, or equivalent boundary.");
   const codexPath = resolveCodexPath();
   const child = spawn("npx", npxArgs, {
@@ -162,6 +184,23 @@ export async function start(args = []) {
   });
 }
 
+async function assertPortAvailable(host, port) {
+  await new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", (error) => {
+      if (error?.code === "EADDRINUSE") {
+        reject(new Error(`Port ${port} is already in use on ${host}. Codex WebApp may already be running. Close the other terminal window, or start with --port <port>.`));
+        return;
+      }
+      reject(error);
+    });
+    server.once("listening", () => {
+      server.close(resolve);
+    });
+    server.listen(port, host);
+  });
+}
+
 export function help() {
   console.log(`${BANNER}
 
@@ -176,8 +215,16 @@ Commands:
   codex-webapp smoke --url http://127.0.0.1:8214/
   codex-webapp smoke --browser --screenshot artifacts/codex-webapp.png
 
-Quick start:
-  npx codex-webapp doctor
+Quick start from Codex App:
+  Paste a request that asks Codex to run:
+    npx -y codex-webapp doctor
+    npx -y codex-webapp start
+  Then open:
+    ${DEFAULT_WEB_URL}
+
+Terminal quick start:
+  npx -y codex-webapp doctor
+  npx -y codex-webapp start
 `);
 }