visual-remote 0.1.0 → 0.1.2

package/README.md

@@ -16,13 +16,23 @@
 Node.js와 pnpm 버전은 각각 `.nvmrc`와 `package.json`에 고정되어 있습니다.
 다른 Node.js 버전에서는 `engine-strict` 설정으로 설치가 중단됩니다.
 
-## npm 설치
+## 가장 빠른 사용
 
-npmjs에서 전역으로 설치합니다.
+기존 앱이 실행 중인 프로젝트에서 그 주소만 전달합니다.
+
+```bash
+npx --yes visual-remote@latest http://localhost:9011
+```
+
+명령이 출력한 `Gateway` 주소로 접속하면 Visual Remote가 포함된 같은 화면이
+열립니다. 원래 `localhost:9011` 화면은 그대로 유지됩니다. `10001`이 사용 중이면
+`10002`, `10003` 순서로 빈 Gateway 포트를 자동 선택합니다.
+
+전역 설치를 선호하면 다음처럼 사용합니다.
 
 ```bash
 npm install --global visual-remote
-visual doctor
+visual http://localhost:9011
 ```
 
 ## 빠른 시작
@@ -72,26 +82,23 @@ corepack pnpm test
 
 ## 기존 개발 서버에 연결
 
-먼저 대상 애플리케이션의 개발 서버를 `10001` 이상의 포트에서 실행합니다. 다음
-예시는 애플리케이션이 `0.0.0.0:10002`에서 실행 중인 경우입니다.
+먼저 대상 애플리케이션을 평소처럼 실행합니다. 다음 예시는 애플리케이션이
+`localhost:9011`에서 실행 중인 경우입니다.
 
 ```bash
-node apps/cli/dist/index.js attach \
-  --upstream http://127.0.0.1:10002 \
-  --listen 10001 \
-  --public-url https://visual.example.com
+npx --yes visual-remote@latest http://localhost:9011
 ```
 
-브리지는 `0.0.0.0:10001`에 바인딩하고 다음과 같은 주소를 출력합니다.
+브리지는 `10001`부터 빈 포트를 찾아 다음과 같은 주소를 출력합니다.
 
 ```text
-Gateway:  http://dev:10001
-Public:   https://visual.example.com/
-Open:     https://visual.example.com/
+Gateway:  http://localhost:10001
+Upstream: http://localhost:9011/
+Open:     http://localhost:10001
 ```
 
-브라우저에서는 출력된 공개 주소를 바로 엽니다. 별도의 페어링 링크나 토큰은
-필요하지 않습니다.
+브라우저에서는 출력된 `Gateway` 또는 `Open` 주소를 엽니다. 별도의 페어링 링크나
+토큰은 필요하지 않습니다.
 
 Portr를 사용한다면 원래 개발 서버 포트가 아니라 브리지 Gateway 포트 `10001`을
 노출해야 합니다. 앱 화면, 개발 서버의 HMR, 브리지 제어 채널이 한 출처를
@@ -99,10 +106,11 @@ Portr를 사용한다면 원래 개발 서버 포트가 아니라 브리지 Gate
 항상 사용한다면 `.visualdev/config.local.yaml`의 `gateway.publicUrl`로도 설정할 수
 있습니다.
 
-## 개발 서버와 브리지를 함께 실행
+## 선택 사항: 앱 실행까지 함께 관리
 
-저장소 루트에 `.visualdev/config.yaml`을 만듭니다. 명령은 셸 문자열이 아니라
-인자 배열로 작성합니다.
+대상 저장소 루트에서 `visual init`을 실행하면 패키지 매니저와 `dev` 스크립트를
+감지해 `.visualdev/config.yaml`을 생성합니다. 기존 파일은 덮어쓰지 않습니다.
+직접 작성할 때 명령은 셸 문자열이 아니라 인자 배열로 작성합니다.
 
 ```yaml
 version: 1
@@ -113,7 +121,7 @@ project:
 
 gateway:
   host: 0.0.0.0
-  port: 10001
+  port: auto
   # publicUrl: https://visual.example.com
 
 upstream:
@@ -200,14 +208,18 @@ Overlay에서 `작업 보드 ↗`를 다시 눌러 새 세션을 엽니다. 연
 현재 제공하는 명령은 다음과 같습니다.
 
 ```bash
+npx visual-remote http://localhost:9011
+visual init
 visual attach --help
 visual dev --help
 visual status
 visual doctor
 ```
 
-- `attach`: 이미 실행 중인 개발 서버 앞에 브리지를 연결합니다.
-- `dev`: 설정된 개발 서버와 브리지를 함께 실행합니다.
+- 기본 명령: 전달한 기존 앱 주소 앞에 브리지를 연결합니다.
+- `attach`: 기본 명령의 명시적 이름이며 기존 사용법과 호환됩니다.
+- `init`: 선택적으로 앱 실행까지 관리할 때 기본 설정을 생성합니다.
+- `dev`: `init` 설정을 사용해 앱과 브리지를 함께 실행하는 선택 명령입니다.
 - `status`: 현재 Git 작업 트리의 브리지 실행 상태를 확인합니다.
 - `doctor`: Git, 설정 파일, 개발 명령과 Codex 사용 가능 여부를 점검합니다.
 
@@ -273,5 +285,5 @@ node --version
 ### 설정 파일 경고가 표시되는 경우
 
 기존 서버에 연결하는 `attach`는 설정 파일 없이도 기본값으로 실행할 수 있습니다.
-브리지가 개발 서버를 직접 관리해야 한다면 `.visualdev/config.yaml`을 작성한 뒤
-`doctor`를 다시 실행합니다.
+브리지가 개발 서버를 직접 관리해야 한다면 `visual init`을 실행한 뒤 `doctor`를
+다시 실행합니다.

package/apps/cli/dist/index.js

@@ -565,7 +565,7 @@ Content-Length: 0\r
   }
 }
 function gatewayDisplayHost(host) {
-  if (host === "0.0.0.0" || host === "::") return "dev";
+  if (host === "0.0.0.0" || host === "::") return "localhost";
   return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 function createGatewayServer(options) {
@@ -5174,6 +5174,134 @@ function formatDoctorChecks(checks) {
   }).join("\n");
 }
 
+// src/init.ts
+import { readFile as readFile5, mkdir as mkdir3, stat as stat3, writeFile as writeFile3 } from "node:fs/promises";
+import { basename as basename2, dirname as dirname3, join as join5 } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+function isMissingFile(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+async function fileExists2(path) {
+  try {
+    await stat3(path);
+    return true;
+  } catch (error) {
+    if (isMissingFile(error)) return false;
+    throw error;
+  }
+}
+function packageManagerFromField(value) {
+  if (typeof value !== "string") return void 0;
+  const name = value.split("@", 1)[0];
+  return name === "bun" || name === "npm" || name === "pnpm" || name === "yarn" ? name : void 0;
+}
+async function detectPackageManager(repoRoot, manifest) {
+  const declared = packageManagerFromField(manifest.packageManager);
+  if (declared !== void 0) return declared;
+  const lockfiles = [
+    ["pnpm", "pnpm-lock.yaml"],
+    ["yarn", "yarn.lock"],
+    ["bun", "bun.lock"],
+    ["bun", "bun.lockb"],
+    ["npm", "package-lock.json"]
+  ];
+  for (const [manager, filename] of lockfiles) {
+    if (await fileExists2(join5(repoRoot, filename))) return manager;
+  }
+  return "npm";
+}
+function readDevScript(manifest) {
+  if (typeof manifest.scripts !== "object" || manifest.scripts === null || !("dev" in manifest.scripts) || typeof manifest.scripts.dev !== "string" || manifest.scripts.dev.trim().length === 0) {
+    throw new Error('visual init requires a non-empty "dev" script in package.json');
+  }
+  return manifest.scripts.dev.trim();
+}
+function devCommand(manager, script) {
+  const command = manager === "pnpm" ? ["corepack", "pnpm", "run", "dev"] : manager === "yarn" ? ["corepack", "yarn", "run", "dev"] : manager === "bun" ? ["bun", "run", "dev"] : ["npm", "run", "dev"];
+  const next = /(^|[\s;&|])next(?:\s|$)/.test(script);
+  return [
+    ...command,
+    "--",
+    next ? "--hostname" : "--host",
+    "0.0.0.0",
+    "--port",
+    "{upstreamPort}"
+  ];
+}
+async function readManifest(repoRoot) {
+  const manifestPath = join5(repoRoot, "package.json");
+  let source;
+  try {
+    source = await readFile5(manifestPath, "utf8");
+  } catch (error) {
+    if (isMissingFile(error)) {
+      throw new Error("visual init requires package.json at the Git worktree root");
+    }
+    throw error;
+  }
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    throw new Error(`Unable to parse ${manifestPath}`, { cause: error });
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${manifestPath} must contain a JSON object`);
+  }
+  return value;
+}
+async function initializeVisualDev(dependencies = {}) {
+  const repoRoot = await discoverGitWorktreeRoot(dependencies.cwd ?? process.cwd());
+  const configPath = join5(repoRoot, CONFIG_PATH);
+  if (await fileExists2(configPath)) {
+    return { created: false, configPath };
+  }
+  const manifest = await readManifest(repoRoot);
+  const devScript = readDevScript(manifest);
+  const packageManager = await detectPackageManager(repoRoot, manifest);
+  const document = {
+    version: 1,
+    project: {
+      id: basename2(repoRoot),
+      workspace: "."
+    },
+    gateway: {
+      host: "0.0.0.0",
+      port: "auto"
+    },
+    upstream: {
+      port: "auto",
+      command: devCommand(packageManager, devScript)
+    }
+  };
+  await mkdir3(dirname3(configPath), { recursive: true });
+  try {
+    await writeFile3(configPath, stringifyYaml(document), {
+      encoding: "utf8",
+      flag: "wx"
+    });
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") {
+      return { created: false, configPath };
+    }
+    throw error;
+  }
+  return { created: true, configPath, devScript, packageManager };
+}
+function formatInitResult(result) {
+  if (!result.created) {
+    return [
+      `Already initialized: ${CONFIG_PATH}`,
+      "Next: npx --yes visual-remote@latest dev"
+    ].join("\n");
+  }
+  return [
+    `Created:  ${CONFIG_PATH}`,
+    `Detected: ${result.packageManager} dev (${result.devScript})`,
+    "Next:     npx --yes visual-remote@latest dev"
+  ].join("\n");
+}
+
 // src/status.ts
 async function getBridgeStatus(dependencies = {}) {
   const repoRoot = await discoverGitWorktreeRoot(dependencies.cwd ?? process.cwd());
@@ -5224,10 +5352,28 @@ function setExitCode(dependencies, code) {
   }
 }
 function createCli(dependencies = {}) {
-  const program = new Command().name("visual").description("Visual Remote Dev Bridge").version("0.1.0");
-  program.command("attach").description("Attach the Bridge to an existing development server").requiredOption("--upstream <url>", "existing development server URL").option("--listen <port>", "gateway port (10001 or above)", parsePort).option("--host <host>", "gateway bind host (default: 0.0.0.0)").option("--public-url <url>", "public Gateway URL opened in the browser").action(
-    async (options) => {
-      const bridge = await startAttachBridge(options, dependencies);
+  const program = new Command().name("visual").description("Visual Remote Dev Bridge").version("0.1.2");
+  program.command("init").description("Create .visualdev/config.yaml for the current project").action(async () => {
+    const result = await initializeVisualDev(dependencies);
+    output(dependencies, formatInitResult(result));
+  });
+  program.command("attach [upstream]", { isDefault: true }).description("Attach the Bridge to an existing development server").option("--upstream <url>", "existing development server URL").option("--listen <port>", "gateway port (10001 or above)", parsePort).option("--host <host>", "gateway bind host (default: 0.0.0.0)").option("--public-url <url>", "public Gateway URL opened in the browser").action(
+    async (upstream, options) => {
+      const upstreamUrl = options.upstream ?? upstream;
+      if (upstreamUrl === void 0) {
+        throw new Error(
+          "Provide the running app URL, for example: npx visual-remote http://localhost:9011"
+        );
+      }
+      const bridge = await startAttachBridge(
+        {
+          upstream: upstreamUrl,
+          ...options.listen === void 0 ? {} : { listen: options.listen },
+          ...options.host === void 0 ? {} : { host: options.host },
+          ...options.publicUrl === void 0 ? {} : { publicUrl: options.publicUrl }
+        },
+        dependencies
+      );
       output(dependencies, formatBridgeSummary(bridge));
       await runBridgeUntilSignal(bridge);
     }
@@ -5271,7 +5417,9 @@ export {
   formatBridgeStatus,
   formatBridgeSummary,
   formatDoctorChecks,
+  formatInitResult,
   getBridgeStatus,
+  initializeVisualDev,
   main,
   runBridgeUntilSignal,
   runDoctor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-remote",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Visual bridge from a running web UI to Codex in its Git worktree",
   "type": "module",
   "repository": {
@@ -43,10 +43,10 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
     "@visual-remote/bridge-core": "0.1.0",
-    "@visual-remote/gateway": "0.1.0",
-    "@visual-remote/cli": "0.1.0",
+    "@visual-remote/protocol": "0.1.0",
     "@visual-remote/overlay": "0.1.0",
-    "@visual-remote/protocol": "0.1.0"
+    "@visual-remote/cli": "0.1.0",
+    "@visual-remote/gateway": "0.1.0"
   },
   "scripts": {
     "build": "corepack pnpm run build:overlay && corepack pnpm run build:server",