@codex-app-sdk/create-codex-app 0.0.0-stage → 0.14.1

package/template/src/main/preload.ts

@@ -0,0 +1,4 @@
+import { contextBridge, ipcRenderer } from 'electron';
+import { exposeCodexElectronPreload } from '@codex-app-sdk/electron/preload';
+
+exposeCodexElectronPreload(contextBridge, ipcRenderer);

package/template/src/renderer/App.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { CodexConversationPane, useCodexSurface } from '@codex-app-sdk/vue';
+
+const surface = useCodexSurface(window.codexSurface);
+const localSignInError = ref<string | null>(null);
+const requiresSignIn = computed(() => (
+  surface.state.authentication.account === null
+  && surface.state.authentication.requiresOpenaiAuth === true
+));
+const signInBusy = computed(() => (
+  surface.state.authentication.login.status === 'starting'
+  || surface.state.authentication.login.status === 'pending'
+));
+const signInError = computed(() => (
+  localSignInError.value
+  ?? surface.state.authentication.login.error
+  ?? surface.state.authentication.error
+));
+
+async function signIn(): Promise<void> {
+  localSignInError.value = null;
+  let loginId: string | undefined;
+  try {
+    const login = await surface.startChatGptLogin();
+    loginId = login.loginId;
+    await window.codexAppSdkNative.openExternal(login.authUrl);
+  } catch {
+    if (loginId) await surface.cancelLogin(loginId).catch(() => undefined);
+    localSignInError.value = 'Could not open Codex sign in. Please try again.';
+  }
+}
+</script>
+
+<template>
+  <main class="app-shell">
+    <aside class="sidebar" aria-label="Conversations">
+      <header class="sidebar__header">
+        <strong class="sidebar__brand">{{displayName}}</strong>
+      </header>
+      <div class="sidebar__actions">
+        <button
+          type="button"
+          class="sidebar__new-chat"
+          :disabled="surface.state.status !== 'ready'"
+          @click="surface.createConversation()"
+        >
+          <svg aria-hidden="true" viewBox="0 0 24 24">
+            <path d="M12 20h9" />
+            <path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L8 18l-4 1 1-4Z" />
+          </svg>
+          <span>New chat</span>
+        </button>
+      </div>
+
+      <section class="sidebar__recents" aria-labelledby="recent-chats-heading">
+        <h2 id="recent-chats-heading" class="sidebar__section-title">Recent chats</h2>
+        <p v-if="surface.state.conversations.length === 0" class="sidebar__empty">
+          {{ surface.state.status === 'connecting' ? 'Loading…' : 'No conversations yet' }}
+        </p>
+        <nav v-else class="sidebar__list" aria-label="Recent chats">
+          <button
+            v-for="conversation in surface.state.conversations"
+            :key="conversation.id"
+            type="button"
+            class="sidebar__conversation"
+            :class="{ 'sidebar__conversation--active': conversation.id === surface.state.activeConversationId }"
+            :title="conversation.title || 'Untitled conversation'"
+            @click="surface.selectConversation(conversation.id)"
+          >
+            <span>{{ conversation.title || 'Untitled conversation' }}</span>
+          </button>
+        </nav>
+      </section>
+    </aside>
+
+    <section v-if="requiresSignIn" class="auth-landing">
+      <div class="auth-landing__card">
+        <span class="auth-landing__mark" aria-hidden="true">✦</span>
+        <h1>Connect Codex</h1>
+        <p>Sign in to start conversations and build with Codex in this app.</p>
+        <button type="button" :disabled="signInBusy" @click="signIn">
+          {{ signInBusy ? 'Waiting for sign in…' : 'Sign in with ChatGPT' }}
+        </button>
+        <p v-if="signInError" class="auth-landing__error" role="alert">{{ signInError }}</p>
+      </div>
+    </section>
+    <CodexConversationPane v-else :surface="surface" autofocus />
+  </main>
+</template>

package/template/src/renderer/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; media-src 'self' blob:; font-src 'self' data:; connect-src 'self' ws://127.0.0.1:* ws://localhost:*; worker-src 'self' blob:; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'"
+    />
+    <title>{{displayName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/template/src/renderer/main.ts

@@ -0,0 +1,11 @@
+import { createApp } from 'vue';
+import '@codex-app-sdk/vue/styles.css';
+import App from './App.vue';
+import './styles.css';
+
+document.documentElement.dataset.platform = navigator.platform.startsWith('Mac')
+  || navigator.userAgent.includes('Macintosh')
+  ? 'macos'
+  : 'other';
+
+createApp(App).mount('#app');

package/template/src/renderer/styles.css

@@ -0,0 +1,204 @@
+:root {
+  color: #20211f;
+  background: #f7f7f5;
+  font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-synthesis: none;
+  --codex-surface-color: #fff;
+  --codex-composer-background: #fff;
+  --codex-border-color: #deded9;
+  --codex-message-list-content-width: 760px;
+  --codex-composer-content-width: 760px;
+  --color-surface-lowest: #fff;
+  --color-surface-low: #f4f4f4;
+  --color-shell-main: var(--color-surface-lowest);
+  --shell-glass-opacity: 65%;
+  --color-shell-sidebar: var(--color-surface-low);
+  --color-shell-appbar-divider: color-mix(in srgb, #b0b0b0 14%, transparent);
+  --workbench-appbar-height: 48px;
+}
+
+html[data-platform='macos'] {
+  background: transparent;
+  --color-shell-sidebar: color-mix(in srgb, var(--color-shell-main) var(--shell-glass-opacity), transparent);
+}
+
+* { box-sizing: border-box; }
+html, body, #app { width: 100%; height: 100%; margin: 0; }
+button { font: inherit; }
+
+.app-shell {
+  display: grid;
+  width: 100%;
+  height: 100%;
+  grid-template-columns: 248px minmax(0, 1fr);
+  overflow: hidden;
+  background: transparent;
+}
+
+.sidebar {
+  display: flex;
+  min-height: 0;
+  flex-direction: column;
+  border-right: 1px solid #deded9;
+  background: var(--color-shell-sidebar);
+  user-select: none;
+}
+
+.sidebar__header {
+  display: flex;
+  min-width: 0;
+  height: var(--workbench-appbar-height);
+  flex: 0 0 var(--workbench-appbar-height);
+  align-items: center;
+  padding: 0 12px 0 20px;
+  border-bottom: 1px solid var(--color-shell-appbar-divider);
+  -webkit-app-region: drag;
+}
+
+html[data-platform='macos'] .sidebar__header {
+  padding-left: 88px;
+}
+
+.sidebar__brand {
+  min-width: 0;
+  overflow: hidden;
+  font-size: 14px;
+  font-weight: 650;
+  line-height: 20px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.sidebar__actions {
+  padding: 10px 8px 4px;
+}
+
+.sidebar__actions .sidebar__new-chat {
+  width: 100%;
+}
+
+.sidebar button {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  border: 0;
+  border-radius: 8px;
+  padding: 7px 10px;
+  color: #2a2b29;
+  background: transparent;
+  font-size: 13px;
+  line-height: 20px;
+  text-align: left;
+  cursor: pointer;
+  -webkit-app-region: no-drag;
+}
+
+.sidebar button.sidebar__new-chat {
+  gap: 9px;
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.sidebar__new-chat svg {
+  width: 17px;
+  height: 17px;
+  flex: 0 0 auto;
+  fill: none;
+  stroke: currentColor;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: 1.8;
+}
+
+.sidebar button:hover,
+.sidebar button:focus-visible,
+.sidebar__conversation--active { background: #e2e2dd; }
+.sidebar button:focus-visible { outline: 2px solid #3b82f6; outline-offset: -2px; }
+.sidebar button:disabled { cursor: not-allowed; opacity: 0.55; }
+
+.sidebar__recents {
+  display: flex;
+  min-height: 0;
+  flex-direction: column;
+  flex: 1;
+}
+
+.sidebar__section-title {
+  margin: 6px 20px 7px;
+  color: #85857e;
+  font-size: 11px;
+  font-weight: 650;
+  line-height: 16px;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.sidebar__list {
+  display: flex;
+  min-height: 0;
+  padding: 0 8px 12px;
+  overflow-y: auto;
+  flex-direction: column;
+  gap: 1px;
+}
+
+.sidebar__conversation span {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.sidebar__conversation--active { font-weight: 600; }
+.sidebar__empty { margin: 0; padding: 5px 20px; color: #85857e; font-size: 12px; }
+
+.auth-landing {
+  display: grid;
+  min-width: 0;
+  min-height: 0;
+  place-items: center;
+  padding: 40px;
+  background: var(--color-shell-main);
+}
+
+.auth-landing__card {
+  display: grid;
+  width: min(420px, 100%);
+  justify-items: center;
+  border: 1px solid var(--codex-border-color);
+  border-radius: 18px;
+  padding: 34px;
+  background: #fff;
+  box-shadow: 0 14px 36px rgb(0 0 0 / 6%);
+  text-align: center;
+}
+.auth-landing__mark {
+  display: grid;
+  width: 44px;
+  height: 44px;
+  place-items: center;
+  border-radius: 14px;
+  color: #4f46e5;
+  background: #eeedff;
+  font-size: 24px;
+}
+.auth-landing h1 { margin: 16px 0 0; font-size: 24px; }
+.auth-landing p { margin: 9px 0 0; color: #6a6b66; font-size: 14px; line-height: 1.5; }
+.auth-landing button {
+  min-height: 42px;
+  margin-top: 24px;
+  border: 0;
+  border-radius: 10px;
+  padding: 0 20px;
+  color: #fff;
+  background: #4f46e5;
+  font-weight: 650;
+  cursor: pointer;
+}
+.auth-landing button:hover:not(:disabled) { background: #4338ca; }
+.auth-landing button:disabled { cursor: wait; opacity: 0.65; }
+.auth-landing .auth-landing__error { color: #b42318; font-size: 12px; }
+
+@media (max-width: 720px) {
+  .app-shell { grid-template-columns: 190px minmax(0, 1fr); }
+}

package/template/src/renderer/vite-env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+import type { CodexNativeRendererApi, CodexSurfaceRendererApi } from '@codex-app-sdk/electron';
+
+declare global {
+  interface Window {
+    codexAppSdkNative: CodexNativeRendererApi;
+    codexSurface: CodexSurfaceRendererApi;
+  }
+}
+
+export {};

package/template/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,62 @@
+import { fileURLToPath, URL } from 'node:url';
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+import electron from 'vite-plugin-electron/simple';
+
+const projectRoot = fileURLToPath(new URL('.', import.meta.url));
+const mainEntry = fileURLToPath(new URL('./src/main/index.ts', import.meta.url));
+const preloadEntry = fileURLToPath(new URL('./src/main/preload.ts', import.meta.url));
+const mainOutDir = fileURLToPath(new URL('./dist-main', import.meta.url));
+const rendererRoot = fileURLToPath(new URL('./src/renderer', import.meta.url));
+const rendererOutDir = fileURLToPath(new URL('./dist-renderer', import.meta.url));
+
+export default defineConfig(({ command, mode }) => ({
+  base: './',
+  root: rendererRoot,
+  plugins: [
+    vue(),
+    (command === 'build' || mode === 'electron') && electron({
+      main: {
+        entry: mainEntry,
+        onstart: async ({ startup }) => {
+          await startup(['.'], { cwd: projectRoot });
+        },
+        vite: {
+          root: projectRoot,
+          build: {
+            outDir: mainOutDir,
+            emptyOutDir: command === 'build',
+            lib: { entry: mainEntry, fileName: () => 'main.js' },
+            rolldownOptions: { external: command === 'build' ? [/^@codex-app-sdk\//] : [] },
+          },
+        },
+      },
+      preload: {
+        input: preloadEntry,
+        vite: {
+          root: projectRoot,
+          build: {
+            outDir: mainOutDir,
+            emptyOutDir: false,
+            rolldownOptions: {
+              output: {
+                format: 'cjs',
+                codeSplitting: false,
+                entryFileNames: 'preload.cjs',
+                chunkFileNames: '[name].cjs',
+                assetFileNames: '[name].[ext]',
+              },
+            },
+          },
+        },
+      },
+    }),
+  ],
+  server: { host: '127.0.0.1', port: 5173, strictPort: true },
+  build: {
+    outDir: rendererOutDir,
+    emptyOutDir: true,
+    // The stock conversation pane includes local syntax-highlighting grammars.
+    chunkSizeWarningLimit: 4_000,
+  },
+}));

package/template-web/README.md

@@ -0,0 +1,30 @@
+# {{displayName}}
+
+Express, `ws`, and Vue application powered by [Codex App SDK](https://github.com/codex-app-sdk/codex-app-sdk).
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://127.0.0.1:3000`. The starter uses the default Codex home and its
+existing local authentication.
+
+The generated renderer contains only the SDK web client and stock conversation
+sidebar/pane wiring. Express owns HTTP and site authentication; `ws` owns the
+upgrade; the SDK owns protocol framing and surface routing. Replace
+`authenticateSiteRequest()` and `acquireCodexSession()` with your website's
+session lookup and per-user backend/process pool. Stable `codexHome`
+directories, stored tokens, quotas, and persistence remain host concerns.
+
+The SDK transport is framework-neutral; Express and `ws` make the generated
+boundary runnable but are not dependencies of `@codex-app-sdk/web`. See the
+[web integration guide](https://codex-app-sdk.github.io/codex-app-sdk/guide/web.html)
+before replacing the demo authorization seams.
+
+## Commands
+
+- `npm run dev` builds and starts the local server.
+- `npm run build` creates the browser and server bundles.
+- `npm start` builds and starts the application.
+- `npm run typecheck` checks the TypeScript and Vue source.

package/template-web/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.DS_Store
+*.log

package/template-web/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{packageName}}",
+  "productName": "{{displayName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npm run build && node dist/server/index.js",
+    "build": "vite build && tsc -p tsconfig.server.json",
+    "start": "npm run build && node dist/server/index.js",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.server.json"
+  },
+  "dependencies": {
+    "@codex-app-sdk/backend": "^0.14.1",
+    "@codex-app-sdk/core": "^0.14.1",
+    "@codex-app-sdk/vue": "^0.14.1",
+    "@codex-app-sdk/web": "^0.14.1",
+    "express": "^5.1.0",
+    "vue": "^3.5.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "typescript": "^6.0.0",
+    "vite": "^8.0.0",
+    "vue-tsc": "^3.3.0"
+  }
+}

package/template-web/src/client/App.vue

@@ -0,0 +1,36 @@
+<template>
+  <main class="web-app">
+    <CodexConversationSidebar
+      brand="{{displayName}}"
+      :active-conversation-id="surface.state.activeConversationId"
+      :conversations="surface.state.conversations"
+      :create-disabled="surface.state.status !== 'ready'"
+      :loading="surface.state.status === 'connecting'"
+      @create="surface.createConversation()"
+      @delete="surface.deleteConversation($event)"
+      @select="surface.selectConversation($event)"
+    />
+    <CodexConversationPane :surface="surface" autofocus />
+  </main>
+</template>
+
+<script setup lang="ts">
+import {
+  CodexConversationPane,
+  CodexConversationSidebar,
+  useCodexSurface,
+} from '@codex-app-sdk/vue';
+import {
+  createCodexBrowserWebSocketPort,
+  createCodexWebSurfaceClient,
+} from '@codex-app-sdk/web/client';
+
+const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+const api = createCodexWebSurfaceClient({
+  createSocket: () => createCodexBrowserWebSocketPort(
+    new WebSocket(`${protocol}//${window.location.host}/codex`),
+  ),
+  reconnect: true,
+});
+const surface = useCodexSurface(api);
+</script>

package/template-web/src/client/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; connect-src 'self' ws: wss:; font-src 'self' data:; img-src 'self' data: blob: https:; style-src 'self' 'unsafe-inline'; script-src 'self'"
+    />
+    <title>{{displayName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/template-web/src/client/main.ts

@@ -0,0 +1,6 @@
+import { createApp } from 'vue';
+import '@codex-app-sdk/vue/styles.css';
+import App from './App.vue';
+import './styles.css';
+
+createApp(App).mount('#app');

package/template-web/src/client/styles.css

@@ -0,0 +1,44 @@
+:root {
+  color: #20211f;
+  background: #f7f7f5;
+  font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-synthesis: none;
+  --codex-surface-color: #fff;
+  --codex-composer-background: #fff;
+  --codex-border-color: #deded9;
+  --codex-message-list-content-width: 760px;
+  --codex-composer-content-width: 760px;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#app,
+.web-app {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  background: #f7f7f5;
+}
+
+button,
+textarea {
+  font: inherit;
+}
+
+.web-app {
+  display: grid;
+  min-width: 320px;
+  grid-template-columns: 260px minmax(0, 1fr);
+  overflow: hidden;
+}
+
+@media (max-width: 760px) {
+  .web-app { grid-template-columns: 210px minmax(0, 1fr); }
+}

package/template-web/src/client/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template-web/src/server/index.ts

@@ -0,0 +1,81 @@
+import { createServer, type IncomingMessage } from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { WebSocketServer } from 'ws';
+import { createCodexAppBackend } from '@codex-app-sdk/backend';
+import {
+  bindCodexWebSocket,
+  createCodexNodeWebSocketPort,
+  isAllowedCodexWebSocketOrigin,
+} from '@codex-app-sdk/web/server';
+
+type SiteUser = { id: string };
+type WebSessionContext = { request: IncomingMessage; siteUser: SiteUser };
+
+const port = Number(process.env.PORT ?? 3000);
+// Browsers let any website open a WebSocket to this server, so only pages
+// served from these origins may drive Codex. Set ALLOWED_ORIGINS
+// (comma-separated) to the public origin when deploying.
+const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(',').map((origin) => origin.trim()).filter(Boolean)
+  ?? [`http://127.0.0.1:${port}`, `http://localhost:${port}`];
+const clientDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../client');
+const app = express();
+const httpServer = createServer(app);
+const webSocketServer = new WebSocketServer({ noServer: true });
+const backend = createCodexAppBackend({
+  surfaceOptions: { autoSelectFirstConversation: false },
+});
+
+app.use(express.static(clientDirectory));
+app.get('/', (_request, response) => response.sendFile(path.join(clientDirectory, 'index.html')));
+
+httpServer.on('upgrade', (request, socket, head) => {
+  const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
+  if (pathname !== '/codex' || !isAllowedCodexWebSocketOrigin(request, allowedOrigins)) {
+    socket.destroy();
+    return;
+  }
+  const siteUser = authenticateSiteRequest(request);
+  if (!siteUser) {
+    socket.destroy();
+    return;
+  }
+
+  webSocketServer.handleUpgrade(request, socket, head, (webSocket) => {
+    const binding = bindCodexWebSocket({
+      socket: createCodexNodeWebSocketPort(webSocket),
+      context: { request, siteUser },
+      authorize: acquireCodexSession,
+    });
+    void binding.ready.catch((error: unknown) => {
+      console.error('Codex web session failed:', error);
+    });
+  });
+});
+
+httpServer.listen(port, '127.0.0.1', () => {
+  console.log(`{{displayName}}: http://127.0.0.1:${port}`);
+});
+
+function authenticateSiteRequest(_request: IncomingMessage): SiteUser | null {
+  // DEMO ONLY: replace this with the website's cookie/session authentication.
+  return { id: 'local-demo-user' };
+}
+
+function acquireCodexSession({ siteUser }: WebSessionContext) {
+  // A production host would acquire this user's isolated backend/process here.
+  return siteUser.id === 'local-demo-user' ? { surface: backend.surface } : null;
+}
+
+async function shutdown(): Promise<void> {
+  for (const client of webSocketServer.clients) client.terminate();
+  await Promise.all([
+    new Promise<void>((resolve) => webSocketServer.close(() => resolve())),
+    new Promise<void>((resolve, reject) => httpServer.close((error) => error ? reject(error) : resolve())),
+    backend.close(),
+  ]);
+}
+
+process.once('SIGINT', () => { void shutdown(); });
+process.once('SIGTERM', () => { void shutdown(); });