@jxsuite/studio 0.34.0 → 0.36.0

package/src/types.ts

@@ -1,127 +1,58 @@
 /// <reference lib="dom" />
-import type {
-  JsonValue as SchemaJsonValue,
-  JxMutableNode,
-  JxPath,
-  ProjectConfig,
-} from "@jxsuite/schema/types";
-
-// ─── Git & Platform Types ───────────────────────────────────────────────────
-
-export interface GitFileStatus {
-  status: string;
-  path: string;
-  staged?: boolean;
-}
-
-export interface GitStatusResult {
-  branch: string;
-  files: GitFileStatus[];
-  ahead: number;
-  behind: number;
-  isRepo: boolean;
-  remotes: string[];
-}
-
-export interface GitBranchesResult {
-  current: string;
-  branches: string[];
-}
-
-export interface GitLogEntry {
-  hash: string;
-  message: string;
-  author: string;
-  date: string;
-}
-
-export interface ComponentSlotMeta {
-  name: string;
-  description?: string;
-  fallback?: (JxMutableNode | string)[];
-}
-
-export interface ComponentMeta {
-  tagName: string;
-  $id?: string | null;
-  path: string;
-  props?: { name: string; type?: string; default?: JsonValue; [k: string]: unknown }[];
-  slots?: ComponentSlotMeta[];
-  hasElements?: boolean;
-}
-
-export interface PackageInfo {
-  name: string;
-  version: string;
-  /** True when the dependency lives in `devDependencies` rather than `dependencies`. */
-  dev?: boolean;
-}
-
-/** A dependency with a newer version available, as reported by `bun outdated` / the npm registry. */
-export interface OutdatedInfo {
-  name: string;
-  /** The version range pinned in package.json (e.g. "^0.19.0"). */
-  current: string;
-  /** The newest published version. */
-  latest: string;
-  /** The newest version satisfying the current range, if known. */
-  wanted?: string;
-  dev?: boolean;
-}
-
-/** Result of a package mutation that runs `bun install` (install / set-versions). */
-export interface PackageOpResult {
-  ok: boolean;
-  /** Combined stdout/stderr from the bun invocation, surfaced to the user on failure. */
-  log?: string;
-}
-
-/** Desktop app/build info surfaced in the About screen. */
-export interface AppInfo {
-  version: string;
-  channel: string;
-  hash: string;
-  /** Human-readable update status (e.g. "Up to date", "Update available"), if known. */
-  updateStatus?: string;
-}
-
-export interface CodeServiceResult {
-  code?: string;
-  diagnostics?: unknown[];
-  [key: string]: unknown;
-}
+import type { JxMutableNode, JxPath, ProjectConfig } from "@jxsuite/schema/types";
 
-export interface DirEntry {
-  name: string;
-  path: string;
-  type: "file" | "directory";
-  size?: number;
-  modified?: string;
-}
+// ─── Wire types (the Studio Backend Protocol) ───────────────────────────────
+/* The request/response shapes every backend serves live in @jxsuite/protocol;
+   re-exported here so existing `../types` imports keep working. */
 
-/** A filesystem change pushed from the backend (project-relative, forward-slashed path). */
-export interface FsEvent {
-  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
-  path: string;
-  isDir: boolean;
-}
+import type {
+  AppInfo,
+  CfConnection,
+  CodeServiceResult,
+  ComponentMeta,
+  DirEntry,
+  FsEvent,
+  GitBranchesResult,
+  GitLogEntry,
+  GitStatusResult,
+  ImportProgressEvent,
+  ImportSiteOptions,
+  OutdatedInfo,
+  PackageInfo,
+  PackageOpResult,
+  ProjectListEntry,
+  RecentProjectEntry,
+  RenameResult,
+  StarterInfo,
+} from "@jxsuite/protocol";
 
-/** Result of a rename, including the references rewritten across the project (refactor report). */
-export interface RenameResult {
-  ok: boolean;
-  from: string;
-  to: string;
-  isDir?: boolean;
-  references?: {
-    filesChanged: number;
-    refsUpdated: number;
-    files: { path: string; count: number }[];
-  };
-  errors?: { path: string; error: string }[];
-  tag?: { from: string; to: string; filesChanged: number; refsUpdated: number };
-  tagSkipped?: string;
-  error?: string;
-}
+export type {
+  AiModelInfo,
+  AiModelsResponse,
+  AppInfo,
+  CfConnection,
+  CodeServiceResult,
+  ComponentMeta,
+  ComponentSlotMeta,
+  DirEntry,
+  ErrorBody,
+  FsEvent,
+  GitBranchesResult,
+  GitFileStatus,
+  GitLogEntry,
+  GitStatusResult,
+  ImportProgressEvent,
+  ImportSiteOptions,
+  JsonValue,
+  OutdatedInfo,
+  PackageInfo,
+  PackageOpResult,
+  ProjectListEntry,
+  PullRequestInfo,
+  RecentProjectEntry,
+  RenameResult,
+  StarterInfo,
+} from "@jxsuite/protocol";
 
 export interface StudioPlatform {
   id: string;
@@ -227,7 +158,41 @@ export interface StudioPlatform {
     url?: string;
     adapter?: string;
     directory: string;
+    /** Id of a starter template to clone, or "blank"/undefined for the minimal template. */
+    starter?: string;
+    /** Id of a built-in template variant (from `@jxsuite/create/templates`); undefined = blank. */
+    template?: string;
+    /** Design quickstart (colors, fonts, logo, breakpoints) applied on top of the scaffold. */
+    design?: {
+      accent?: string;
+      background?: string;
+      text?: string;
+      bodyFont?: string;
+      headingFont?: string;
+      media?: Record<string, string>;
+      logo?: { name: string; base64: string };
+    };
   }) => Promise<{ root: string; config: ProjectConfig }>;
+  /**
+   * List the starter templates available in the New Project picker. Absent on platforms that don't
+   * ship starters (the picker then offers only a blank project).
+   */
+  listStarters?: () => Promise<StarterInfo[]>;
+  /**
+   * AI-guided import of an existing site into a new project. Runs in the backend (headless Chrome +
+   * fs), streaming progress until the project is written. Absent on platforms without a backend
+   * import pipeline — the New Project modal hides its Import tab then.
+   */
+  importSite?: (
+    opts: ImportSiteOptions,
+    onProgress: (evt: ImportProgressEvent) => void,
+    signal?: AbortSignal,
+  ) => Promise<{ root: string; config: ProjectConfig }>;
+  /**
+   * Open a native directory picker and return the chosen absolute path (null when cancelled).
+   * Desktop only; the dev server interprets directories relative to its root instead.
+   */
+  pickDirectory?: () => Promise<string | null>;
   /** Stack B AI assistant: URL of the OpenAI-compatible SSE chat proxy (`/__studio/ai/chat`). */
   aiChatUrl: () => string | Promise<string>;
   // ─── Multi-window (desktop only; undefined on dev-server) ───────────────────
@@ -251,13 +216,51 @@ export interface StudioPlatform {
   getRecentProjects?: () => Promise<RecentProjectEntry[]>;
   /** Persist the full recent-projects list to the backend store. */
   saveRecentProjects?: (projects: RecentProjectEntry[]) => Promise<void>;
-}
-
-/** A recently-opened project, keyed by its re-openable `root` (platform-specific). */
-export interface RecentProjectEntry {
-  name: string;
-  root: string;
-  timestamp: number;
+  // ─── Project catalogue (platforms that can enumerate openable projects) ─────
+  /**
+   * Enumerate every project this platform can open — the dev server's sites under its root, a cloud
+   * platform's remote projects. Entry `root` values re-open through the same paths as recent
+   * projects (openRecentProject). Absent on desktop, where the OS file system is the catalogue and
+   * projects are found via the native picker instead.
+   */
+  listProjects?: () => Promise<ProjectListEntry[]>;
+  // ─── Identity & hosting connections (publish surface) ───────────────────────
+  /** The signed-in user's identity, when the platform has one (cloud). */
+  getUser?: () => Promise<{ login: string; name?: string; avatarUrl?: string } | null>;
+  /**
+   * Open a pull request for the current branch. Cloud platforms implement it against their session;
+   * local platforms omit it and Studio falls back to a direct GitHub API call with the user's
+   * stored token.
+   */
+  createPullRequest?: (opts: {
+    title: string;
+    body?: string;
+    head?: string;
+    base?: string;
+  }) => Promise<{ url: string; number: number }>;
+  /** Current Cloudflare connection state, when the platform can broker one. */
+  cfConnection?: () => Promise<CfConnection | null>;
+  /**
+   * Interactively connect a Cloudflare account (hosted OAuth on the cloud platform). Local
+   * platforms omit it — the publish UI collects an API token instead and verifies via
+   * cfConnection.
+   */
+  cfConnect?: () => Promise<CfConnection | null>;
+  /**
+   * Allowlisted Cloudflare API passthrough (accounts, Pages projects and deployments). The backend
+   * injects credentials — an OAuth token on the cloud platform, the user's pasted API token locally
+   * — so no secret ever rides in the request body.
+   */
+  cfApi?: (path: string, init?: { method?: string; body?: unknown }) => Promise<unknown>;
+  // ─── User settings (backend-persisted; undefined on dev-server) ─────────────
+  /**
+   * Read the user-level settings map (e.g. the AI connection parameters) from a backend store
+   * shared across all projects/windows. Platforms without a native backend (dev server) omit it and
+   * settings live in localStorage only.
+   */
+  getSettings?: () => Promise<Record<string, string>>;
+  /** Persist the full user-level settings map to the backend store. */
+  saveSettings?: (settings: Record<string, string>) => Promise<void>;
 }
 
 // ─── Studio Types ───────────────────────────────────────────────────────────
@@ -325,9 +328,3 @@ export interface ProjectState {
   projectDirs?: string[];
   [key: string]: unknown;
 }
-
-/**
- * A JSON document value, or `undefined` to signal property removal in the mutators. Re-uses the
- * schema's precise recursive JSON model.
- */
-export type JsonValue = SchemaJsonValue | undefined;

package/src/ui/ai-credentials-form.ts

@@ -0,0 +1,205 @@
+/// <reference lib="dom" />
+/**
+ * Ai-credentials-form.ts — reusable AI provider credentials form (key / model / endpoint).
+ *
+ * Extracted from the ai-panel key gate so other hosts (e.g. the New Project modal) can embed the
+ * same form. All draft/model-list state lives inside the closure, so multiple instances never
+ * share state. Persists via src/services/ai-settings.ts on Save.
+ *
+ * @license MIT
+ */
+
+import { html, nothing } from "lit-html";
+import type { TemplateResult } from "lit-html";
+import { fetchAvailableModels, invalidateModelCache } from "../services/ai-models";
+import {
+  getBaseUrl,
+  getModel,
+  getOpenAiKey,
+  hasOpenAiKey,
+  setBaseUrl,
+  setModel,
+  setOpenAiKey,
+} from "../services/ai-settings";
+
+export interface AiCredentialsFormOptions {
+  /** Host re-render scheduler — called whenever the form's internal state changes. */
+  requestRender: () => void;
+  /** Called after Save persists the credentials. */
+  onSaved?: () => void;
+  /** Called when Cancel dismisses the form (Cancel is only offered when a key already exists). */
+  onCancel?: () => void;
+  /** Optional context line (TemplateResult | string) replacing the default blurb. */
+  intro?: unknown;
+}
+
+export interface AiCredentialsForm {
+  render: () => TemplateResult;
+  /** Preload drafts from the stored ai-settings and auto-fetch the model list. */
+  startEdit: () => void;
+}
+
+/**
+ * Create an AI credentials form instance bound to a host's render scheduler.
+ *
+ * @param {AiCredentialsFormOptions} opts
+ * @returns {AiCredentialsForm}
+ */
+export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCredentialsForm {
+  let keyDraft = "";
+  let baseUrlDraft = "";
+  let modelDraft = "";
+
+  /** Fetched from the proxy's /models endpoint (sibling of the chat endpoint). */
+  let availableModels: { id: string; name: string }[] = [];
+  let modelsLoading = false;
+  let modelsError = "";
+
+  /** Open the form pre-filled with the current settings, and load the model list. */
+  function startEdit() {
+    keyDraft = getOpenAiKey();
+    baseUrlDraft = getBaseUrl();
+    modelDraft = getModel();
+    opts.requestRender();
+    // Auto-fetch available models if not already loaded.
+    if (availableModels.length === 0 && !modelsLoading) {
+      void fetchModels();
+    }
+  }
+
+  /** Persist the drafted key + endpoint + model and notify the host. */
+  function save() {
+    setOpenAiKey(keyDraft);
+    setBaseUrl(baseUrlDraft);
+    setModel(modelDraft);
+    keyDraft = "";
+    baseUrlDraft = "";
+    modelDraft = "";
+    // Clear fetched models so they're re-fetched with the new credentials next time.
+    availableModels = [];
+    invalidateModelCache();
+    opts.onSaved?.();
+    opts.requestRender();
+  }
+
+  /** Dismiss the form without saving (only offered when a key already exists). */
+  function cancel() {
+    keyDraft = "";
+    baseUrlDraft = "";
+    modelDraft = "";
+    opts.onCancel?.();
+    opts.requestRender();
+  }
+
+  /**
+   * Fetch available models via src/services/ai-models.ts, preferring the in-form drafts over the
+   * stored settings so the list reflects the credentials being edited. Always forces past the
+   * module cache — this runs on explicit user action (or first open) with possibly-new drafts.
+   */
+  async function fetchModels() {
+    modelsLoading = true;
+    modelsError = "";
+    opts.requestRender();
+    try {
+      availableModels = await fetchAvailableModels({
+        apiKey: getOpenAiKey() || keyDraft,
+        baseUrl: baseUrlDraft || getBaseUrl(),
+        force: true,
+      });
+    } catch (error: unknown) {
+      modelsError = (error as Error).message || "Failed to fetch models";
+    } finally {
+      modelsLoading = false;
+      opts.requestRender();
+    }
+  }
+
+  /** The key + model + endpoint form column. */
+  function render(): TemplateResult {
+    const haveKey = hasOpenAiKey();
+    return html`
+      <div
+        class="ai-creds-form"
+        style="display:flex;flex-direction:column;gap:10px;max-width:320px;text-align:left"
+      >
+        <div style="font-weight:600;align-self:center">AI provider key</div>
+        ${opts.intro === undefined
+          ? html`
+              <div style="font-size:11px;color:var(--fg-dim)">
+                Any OpenAI-compatible key works. Stored locally in this browser; sent only to the
+                Studio proxy (never to a third party except your chosen endpoint).
+              </div>
+            `
+          : html`<div style="font-size:11px;color:var(--fg-dim)">${opts.intro}</div>`}
+        <input
+          type="password"
+          style="width:100%;box-sizing:border-box;padding:6px 8px;border-radius:4px;border:1px solid var(--border);background:var(--bg-input);color:var(--fg);font-size:12px"
+          placeholder="sk-… or any compatible key"
+          .value=${keyDraft}
+          @input=${(e: Event) => {
+            keyDraft = (e.target as HTMLInputElement).value;
+          }}
+        />
+        <div style="font-weight:500;font-size:11px;margin-top:4px">Model</div>
+        ${availableModels.length > 0
+          ? html`
+              <sp-combobox
+                size="s"
+                allows-custom-value
+                .value=${modelDraft}
+                @change=${(e: Event) => {
+                  modelDraft = (e.target as HTMLInputElement).value;
+                }}
+                @input=${(e: Event) => {
+                  modelDraft = (e.target as HTMLInputElement).value;
+                }}
+              >
+                ${availableModels.map(
+                  (m) => html`<sp-menu-item value=${m.id}>${m.name}</sp-menu-item>`,
+                )}
+              </sp-combobox>
+            `
+          : html`
+              <input
+                type="text"
+                style="width:100%;box-sizing:border-box;padding:6px 8px;border-radius:4px;border:1px solid var(--border);background:var(--bg-input);color:var(--fg);font-size:12px"
+                placeholder="Model ID (e.g. gpt-4o, claude-sonnet-4-20250514, etc.)"
+                .value=${modelDraft}
+                @input=${(e: Event) => {
+                  modelDraft = (e.target as HTMLInputElement).value;
+                }}
+              />
+            `}
+        <div style="display:flex;gap:8px;align-items:center">
+          <sp-button size="s" variant="secondary" ?disabled=${modelsLoading} @click=${fetchModels}>
+            ${modelsLoading
+              ? "Fetching…"
+              : availableModels.length > 0
+                ? "Refresh models"
+                : "Fetch models"}
+          </sp-button>
+          ${modelsError
+            ? html`<span style="font-size:10px;color:var(--danger)">${modelsError}</span>`
+            : nothing}
+        </div>
+        <input
+          type="text"
+          style="width:100%;box-sizing:border-box;padding:6px 8px;border-radius:4px;border:1px solid var(--border);background:var(--bg-input);color:var(--fg);font-size:12px"
+          placeholder="Endpoint (optional, e.g. http://localhost:11434/v1)"
+          .value=${baseUrlDraft}
+          @input=${(e: Event) => {
+            baseUrlDraft = (e.target as HTMLInputElement).value;
+          }}
+        />
+        <div style="display:flex;gap:8px;align-self:flex-end">
+          ${haveKey
+            ? html`<sp-button size="s" variant="secondary" @click=${cancel}>Cancel</sp-button>`
+            : nothing}
+          <sp-button size="s" variant="primary" @click=${save}>Save</sp-button>
+        </div>
+      </div>
+    `;
+  }
+
+  return { render, startEdit };
+}

package/src/ui/spectrum.ts

@@ -127,6 +127,10 @@ import { IconVisibility } from "@spectrum-web-components/icons-workflow/src/elem
 import { IconVisibilityOff } from "@spectrum-web-components/icons-workflow/src/elements/IconVisibilityOff.js";
 import { IconArtboard } from "@spectrum-web-components/icons-workflow/src/elements/IconArtboard.js";
 import { IconChat } from "@spectrum-web-components/icons-workflow/src/elements/IconChat.js";
+import { IconSend } from "@spectrum-web-components/icons-workflow/src/elements/IconSend.js";
+import { IconStop } from "@spectrum-web-components/icons-workflow/src/elements/IconStop.js";
+import { IconHistory } from "@spectrum-web-components/icons-workflow/src/elements/IconHistory.js";
+import { IconAttach } from "@spectrum-web-components/icons-workflow/src/elements/IconAttach.js";
 import { IconViewList } from "@spectrum-web-components/icons-workflow/src/elements/IconViewList.js";
 import { IconRailRightClose } from "@spectrum-web-components/icons-workflow/src/elements/IconRailRightClose.js";
 import { IconRailRightOpen } from "@spectrum-web-components/icons-workflow/src/elements/IconRailRightOpen.js";
@@ -272,6 +276,10 @@ const components = [
   ["sp-icon-visibility-off", IconVisibilityOff],
   ["sp-icon-artboard", IconArtboard],
   ["sp-icon-chat", IconChat],
+  ["sp-icon-send", IconSend],
+  ["sp-icon-stop", IconStop],
+  ["sp-icon-history", IconHistory],
+  ["sp-icon-attach", IconAttach],
   ["sp-icon-view-list", IconViewList],
   ["sp-icon-text-bold", IconTextBold],
   ["sp-icon-text-italic", IconTextItalic],