codexpanel 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# codexpanel
+
+codexpanel is a mobile control plane for managing local Codex work from a phone. It provides a Next.js web console, relay service, desktop agent, PostgreSQL-backed durable storage, shared protocol package, and reusable UI package in one monorepo.
+
+## Workspace
+
+- `apps/web`: Next.js phone console plus static admin, device setup, and project docs
+- `apps/relay`: HTTP/SSE/WSS relay service, PostgreSQL/SQLite storage, and device onboarding scripts
+- `apps/agent`: desktop-side agent entrypoint
+- `packages/protocol`: shared schemas and transport helpers
+- `packages/codex-app-server`: Codex app-server connector bindings
+- `packages/ui`: shared React UI primitives
+
+Human reference files, local databases, deployment bundles, server handoff notes, and old demo artifacts live outside the production tree in `files_for_human/` and are ignored by Git.
+
+## Commands
+
+```powershell
+npm run check
+npm run build
+npm run smoke:storage
+npm run test:e2e
+```
+
+## Desktop agent install
+
+The public npm entrypoint is the primary one-line installer for Windows desktop agents:
+
+```powershell
+npx -y codexpanel
+```
+
+By default it downloads the Windows bootstrap script from `https://jd.6a.gs/agent/bootstrap.ps1`, installs or updates the desktop agent under `%LOCALAPPDATA%\CodexPanelAgent`, and starts the agent against the production relay.
+
+If the relay is protected, pass `--access-code <code>` or set `CODEXPANEL_ACCESS_CODE` before running the installer.
+
+Use `--relay` for local or private relay verification:
+
+```powershell
+npx -y codexpanel --relay http://127.0.0.1:4871
+```
+
+Useful options include `--user-id`, `--device-id`, `--device-name`, `--workspace`, `--access-code`, `--no-autostart`, `--no-tunnel`, `--dry-run`, and `--print-command`.
+
+## Storage and deployment
+
+The relay uses `CODEXPANEL_DATABASE_URL` or `DATABASE_URL` for PostgreSQL. If neither is set, it falls back to the local SQLite file at `CODEXPANEL_DB_FILE` for development only. Production startup rejects accidental SQLite fallback unless `CODEXPANEL_ALLOW_SQLITE_IN_PRODUCTION=true` is explicitly set for an emergency.
+
+`npm run smoke:storage` always verifies the SQLite development fallback and the production guard. To verify the PostgreSQL path, set `CODEXPANEL_STORAGE_SMOKE_DATABASE_URL` to a disposable PostgreSQL database URL before running it; the smoke test rewrites its storage tables.
+
+`docker-compose.yml` starts PostgreSQL and the relay together. The auto-deploy script pulls the configured branch, rebuilds Docker Compose, and waits for `/api/health` before declaring the update complete.
+
+## Architecture guardrails
+
+Read [docs/CTO_ARCHITECTURE_DIRECTIVE.md](docs/CTO_ARCHITECTURE_DIRECTIVE.md) before changing Next.js, relay, storage, deployment, auth, protocol, or agent behavior.
+
+- API compatibility is tracked in [docs/api-compatibility-matrix.md](docs/api-compatibility-matrix.md).
+- `npm run check` runs `npm run scan:encoding` before workspace checks.
+- Storage code lives under `apps/relay/src/storage/`; UI code must not import backend or database modules.
+
+See [docs/git-workflow.md](docs/git-workflow.md) for the day-to-day Git and GitHub workflow.

package/bin/codexpanel.cjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const VERSION = "0.1.0";
+const DEFAULT_RELAY_URL = "https://jd.6a.gs";
+
+function usage() {
+  return `
+CodexPanel desktop agent installer
+
+Usage:
+  npx -y codexpanel [install] [options]
+  npx -y codexpanel --relay http://127.0.0.1:4871
+
+Options:
+  --relay, --url <url>          Relay URL. Defaults to CODEXPANEL_RELAY_URL or ${DEFAULT_RELAY_URL}
+  --user, --user-id <id>        CodexPanel user id. Defaults to CODEXPANEL_USER_ID or demo_user_a
+  --device, --device-id <id>    Stable device id. Defaults to the relay bootstrap script's generated id
+  --name, --device-name <name>  Device display name
+  --workspace, --cwd <path>     Default workspace for Codex Desktop/app-server
+  --access-code <code>          Access code for protected relay deployments
+  --mode <mode>                 Agent mode. Defaults to desktop-agent
+  --app-server-listen <url>     Local Codex app-server WebSocket URL
+  --no-autostart                Do not enable Windows login autostart
+  --no-tunnel                   Disable Cloudflare WSS direct tunnel
+  --print-command               Print the equivalent PowerShell bootstrap command
+  --dry-run                     Print resolved installer details without running PowerShell
+  -h, --help                    Show help
+  -v, --version                 Show version
+`.trim();
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    command: "install",
+    relayUrl: process.env.CODEXPANEL_RELAY_URL || process.env.BRIDGECODEX_RELAY_URL || DEFAULT_RELAY_URL,
+    userId: process.env.CODEXPANEL_USER_ID || process.env.BRIDGECODEX_USER_ID || "demo_user_a",
+    deviceId: process.env.CODEXPANEL_DEVICE_ID || process.env.BRIDGECODEX_DEVICE_ID || "",
+    deviceName: process.env.CODEXPANEL_DEVICE_NAME || process.env.BRIDGECODEX_DEVICE_NAME || "",
+    workspace: process.env.CODEXPANEL_WORKSPACE || process.env.BRIDGECODEX_WORKSPACE || "",
+    accessCode: process.env.CODEXPANEL_ACCESS_CODE || process.env.BRIDGECODEX_ACCESS_CODE || "",
+    mode: process.env.CODEXPANEL_AGENT_MODE || process.env.BRIDGECODEX_AGENT_MODE || "desktop-agent",
+    appServerListen: process.env.CODEX_APP_SERVER_LISTEN || "",
+    autoStart: true,
+    tunnelEnabled: true,
+    dryRun: false,
+    printCommand: false,
+    keepScript: false,
+  };
+
+  const readValue = (flag) => {
+    const value = args.shift();
+    if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+    return value;
+  };
+
+  while (args.length) {
+    const arg = args.shift();
+    if (!arg) continue;
+    if (arg === "install" || arg === "setup") {
+      options.command = "install";
+    } else if (arg === "help") {
+      options.help = true;
+    } else if (arg === "version") {
+      options.version = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-v" || arg === "--version") {
+      options.version = true;
+    } else if (arg === "--relay" || arg === "--url") {
+      options.relayUrl = readValue(arg);
+    } else if (arg === "--user" || arg === "--user-id") {
+      options.userId = readValue(arg);
+    } else if (arg === "--device" || arg === "--device-id") {
+      options.deviceId = readValue(arg);
+    } else if (arg === "--name" || arg === "--device-name") {
+      options.deviceName = readValue(arg);
+    } else if (arg === "--workspace" || arg === "--cwd") {
+      options.workspace = readValue(arg);
+    } else if (arg === "--access-code") {
+      options.accessCode = readValue(arg);
+    } else if (arg === "--mode") {
+      options.mode = readValue(arg);
+    } else if (arg === "--app-server-listen") {
+      options.appServerListen = readValue(arg);
+    } else if (arg === "--no-autostart") {
+      options.autoStart = false;
+    } else if (arg === "--no-tunnel") {
+      options.tunnelEnabled = false;
+    } else if (arg === "--print-command") {
+      options.printCommand = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--keep-script") {
+      options.keepScript = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function normalizeRelayUrl(value) {
+  const raw = String(value || "").trim().replace(/\/+$/, "");
+  if (!raw) throw new Error("Relay URL is empty");
+  const withProtocol = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+  const url = new URL(withProtocol);
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`Relay URL must use http or https: ${withProtocol}`);
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+function bootstrapUrl(options) {
+  const url = new URL("/agent/bootstrap.ps1", normalizeRelayUrl(options.relayUrl));
+  url.searchParams.set("userId", options.userId);
+  if (options.deviceId) url.searchParams.set("deviceId", options.deviceId);
+  if (options.deviceName) url.searchParams.set("deviceName", options.deviceName);
+  if (options.workspace) url.searchParams.set("workspace", options.workspace);
+  if (options.accessCode) url.searchParams.set("accessCode", options.accessCode);
+  if (options.mode) url.searchParams.set("mode", options.mode);
+  if (options.appServerListen) url.searchParams.set("appServerListen", options.appServerListen);
+  url.searchParams.set("autoStart", options.autoStart ? "1" : "0");
+  url.searchParams.set("tunnelEnabled", options.tunnelEnabled ? "1" : "0");
+  return url;
+}
+
+function downloadText(url, redirects = 0) {
+  if (redirects > 5) return Promise.reject(new Error(`Too many redirects for ${url}`));
+  const client = url.protocol === "https:" ? https : http;
+  return new Promise((resolve, reject) => {
+    const req = client.get(url, {
+      headers: {
+        "user-agent": `codexpanel-npm/${VERSION}`,
+        "accept": "text/plain, */*",
+      },
+      timeout: 30000,
+    }, (res) => {
+      if ([301, 302, 303, 307, 308].includes(res.statusCode || 0) && res.headers.location) {
+        res.resume();
+        const next = new URL(res.headers.location, url);
+        downloadText(next, redirects + 1).then(resolve, reject);
+        return;
+      }
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => body += chunk);
+      res.on("end", () => {
+        if ((res.statusCode || 0) < 200 || (res.statusCode || 0) >= 300) {
+          const authHint = res.statusCode === 401 || res.statusCode === 403
+            ? " The relay requires an access code; re-run with --access-code <code> or set CODEXPANEL_ACCESS_CODE."
+            : "";
+          reject(new Error(`HTTP ${res.statusCode} while downloading ${url}.${authHint}`));
+          return;
+        }
+        resolve(body.replace(/^\uFEFF/, ""));
+      });
+    });
+    req.on("timeout", () => req.destroy(new Error(`Timeout downloading ${url}`)));
+    req.on("error", reject);
+  });
+}
+
+function powershellPath() {
+  if (process.platform !== "win32") return "pwsh";
+  const candidates = ["pwsh.exe", "powershell.exe"];
+  for (const candidate of candidates) {
+    const result = spawnSync("where.exe", [candidate], { encoding: "utf8", windowsHide: true });
+    const first = (result.stdout || "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
+    if (first) return first;
+  }
+  return "powershell.exe";
+}
+
+function powershellCommand(url) {
+  const escaped = String(url).replace(/'/g, "''");
+  return `powershell -NoProfile -ExecutionPolicy Bypass -Command "irm '${escaped}' | iex"`;
+}
+
+async function install(options) {
+  const url = bootstrapUrl(options);
+  if (options.printCommand) console.log(powershellCommand(url));
+  if (options.dryRun) {
+    console.log(JSON.stringify({
+      ok: true,
+      platform: process.platform,
+      relayUrl: normalizeRelayUrl(options.relayUrl),
+      bootstrapUrl: String(url),
+      userId: options.userId,
+      mode: options.mode,
+      autoStart: options.autoStart,
+      tunnelEnabled: options.tunnelEnabled,
+    }, null, 2));
+    return;
+  }
+
+  if (process.platform !== "win32") {
+    throw new Error("CodexPanel desktop agent installation currently supports Windows. Use --print-command on Windows, or open the relay setup page for this platform.");
+  }
+
+  console.log(`CodexPanel: downloading installer from ${normalizeRelayUrl(options.relayUrl)}`);
+  const script = await downloadText(url);
+  if (!/CodexPanel/i.test(script) || !/desktop-agent/i.test(script)) {
+    throw new Error("Downloaded bootstrap script did not look like the CodexPanel Windows installer.");
+  }
+
+  const tmp = path.join(os.tmpdir(), `codexpanel-bootstrap-${Date.now()}-${Math.random().toString(16).slice(2)}.ps1`);
+  fs.writeFileSync(tmp, Buffer.concat([Buffer.from([0xEF, 0xBB, 0xBF]), Buffer.from(script, "utf8")]));
+
+  console.log("CodexPanel: starting Windows installer");
+  const result = spawnSync(powershellPath(), [
+    "-NoLogo",
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-File",
+    tmp,
+  ], {
+    stdio: "inherit",
+    windowsHide: false,
+  });
+
+  if (!options.keepScript) {
+    try { fs.unlinkSync(tmp); } catch {}
+  } else {
+    console.log(`CodexPanel: kept bootstrap script at ${tmp}`);
+  }
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`PowerShell installer exited with code ${result.status}`);
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (options.help) {
+    console.log(usage());
+    return;
+  }
+  if (options.command !== "install") throw new Error(`Unknown command: ${options.command}`);
+  await install(options);
+}
+
+main().catch((error) => {
+  console.error(`codexpanel: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,7 +1,42 @@
-{
+{
   "name": "codexpanel",
-  "version": "0.0.1",
-  "description": "placeholder package to reserve name",
-  "bin": { "codexpanel": "cli.js" },
-  "license": "MIT"
-}
+  "version": "0.1.0",
+  "description": "CodexPanel mobile control plane monorepo.",
+  "license": "UNLICENSED",
+  "private": false,
+  "bin": {
+    "codexpanel": "bin/codexpanel.cjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "dev:web": "npm run dev -w @codexpanel/web",
+    "build": "npm run build --workspaces --if-present",
+    "check": "npm run scan:encoding && npm run verify:api-contracts && npm run verify:storage && npm run check --workspaces --if-present",
+    "test:e2e": "playwright test",
+    "scan:encoding": "node scripts/scan-encoding.cjs",
+    "verify:api-contracts": "node scripts/verify-api-contracts.mjs",
+    "generate:codex": "npm run generate -w @codexpanel/codex-app-server",
+    "verify:storage": "node scripts/verify-storage-boundary.mjs",
+    "smoke:storage": "node scripts/storage-smoke.cjs",
+    "purge:legacy-plaintext": "node scripts/purge-legacy-plaintext-cache.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.52.0",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}

package/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log('占名成功: codexpanel');

package/codexh5/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log('占名成功: codexh5');

package/codexh5/codexfish/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log('占名成功: codexfish');

package/codexh5/codexfish/codexyes/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log('占名成功: codexyes');

package/codexh5/codexfish/codexyes/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "codexyes",
-  "version": "0.0.1",
-  "description": "placeholder package to reserve name",
-  "bin": { "codexyes": "cli.js" },
-  "license": "MIT"
-}

package/codexh5/codexfish/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "codexfish",
-  "version": "0.0.1",
-  "description": "placeholder package to reserve name",
-  "bin": { "codexfish": "cli.js" },
-  "license": "MIT"
-}

package/codexh5/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "codexh5",
-  "version": "0.0.1",
-  "description": "placeholder package to reserve name",
-  "bin": { "codexh5": "cli.js" },
-  "license": "MIT"
-}