@lessly/app-dev 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @lessly/app-dev
+
+Vite plugin for local development of Lessly Apps. It proxies `/lessly-api/*` to the
+Lessly REST API with an automatically-injected bearer token, exposes the dev
+`import.meta.env` values your App needs, and serves the Module-Federation manifest
+at the origin root.
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { lesslyAppDev } from '@lessly/app-dev';
+
+export default defineConfig({
+  plugins: [lesslyAppDev()],
+});
+```
+
+### Environment
+
+Set these in `.env.local` (they are read from your project's env files):
+
+| Variable            | Required | Purpose                                                        |
+| ------------------- | -------- | -------------------------------------------------------------- |
+| `VITE_PRODUCT_ID`   | standalone only | The Lessly product your App runs under. Required for standalone dev; optional when composed under the shell (`dev:federation`/`dev:shell`), which supplies it at runtime. The plugin **warns and continues** if unset — it never fails the build. |
+| `VITE_API_URL`      | no       | Override the REST API base (defaults per `LESSLY_ENV`).        |
+| `VITE_PRODUCT_SLUG` | no       | Slug used in the shell dev-remote hint.                        |
+| `LESSLY_ENV`        | no       | `staging` (default) or `prod`.                                 |
+| `DEV_API_KEY`       | no       | Headless auth (CI): exchanged for a short-lived token. Never exposed to the client bundle. |
+
+## Authentication
+
+The plugin injects `Authorization: Bearer <token>` on every `/lessly-api/*` request
+using, in order: a valid cached token → a stored token in `~/.lessly/credentials.json`
+→ a refreshed token → `DEV_API_KEY` exchange → interactive device login. Token
+refresh is coordinated across processes with a file lock beside the credentials file.
+
+## Scope: REST-only (v1)
+
+**This plugin proxies HTTP REST calls only. WebSocket upgrades on `/lessly-api/*`
+are intentionally not proxied in v1** — Lessly Apps use the REST API for local
+development, and adding WS proxying (and its auth/reconnect semantics) is deferred
+until a concrete need exists. If you require realtime transport locally, connect to
+the target service directly rather than through the dev proxy.
+
+Cross-site requests to the dev proxy (`Sec-Fetch-Site: cross-site`) are rejected as a
+lightweight drive-by-CSRF defense.

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { Plugin } from 'vite';
+
+type LesslyEnvName = 'staging' | 'prod';
+interface LesslyAppDevOptions {
+    /** Override env; defaults to LESSLY_ENV or 'staging'. */
+    env?: LesslyEnvName;
+    /** Override REST API base; defaults to VITE_API_URL or the env default. */
+    apiUrl?: string;
+    /** Vite dev-server proxy path. Fixed contract C1. */
+    proxyPath?: '/lessly-api';
+}
+interface ResolvedEnv {
+    name: LesslyEnvName;
+    apiUrl: string;
+    authServer: string;
+    profile: LesslyEnvName;
+}
+
+declare function resolveShellDevOrigin(processEnv?: Record<string, string | undefined>): string;
+
+interface LesslyAppDevDeps {
+    /** Override the home dir used to locate ~/.lessly (tests). */
+    homedir?: () => string;
+    /** Override token-provider construction (tests / advanced embedding). */
+    createToken?: (a: {
+        env: ResolvedEnv;
+        apiKeyEnv?: string;
+    }) => {
+        get(): Promise<string>;
+    };
+}
+declare function lesslyAppDev(options?: LesslyAppDevOptions, deps?: LesslyAppDevDeps): Plugin;
+
+export { type LesslyAppDevDeps, type LesslyAppDevOptions, type LesslyEnvName, type ResolvedEnv, lesslyAppDev, resolveShellDevOrigin };

package/dist/index.js

@@ -0,0 +1,472 @@
+// src/index.ts
+import { loadEnv } from "vite";
+
+// src/env.ts
+var HOSTS = {
+  staging: { apiUrl: "https://api.lessly.dev", authServer: "https://auth.lessly.dev" },
+  prod: { apiUrl: "https://api.lessly.com", authServer: "https://auth.lessly.com" }
+};
+function resolveEnv(input = {}) {
+  const pe = input.processEnv ?? process.env;
+  const name = input.env ?? (pe.LESSLY_ENV === "prod" ? "prod" : "staging");
+  const hosts = HOSTS[name];
+  return {
+    name,
+    profile: name,
+    apiUrl: input.apiUrl ?? pe.VITE_API_URL ?? hosts.apiUrl,
+    authServer: hosts.authServer
+  };
+}
+
+// src/proxy.ts
+function buildProxyConfig(args) {
+  const prefix = args.proxyPath;
+  const key = `^${prefix}(?:[/?]|$)`;
+  return {
+    [key]: {
+      target: args.apiUrl,
+      changeOrigin: true,
+      rewrite: (path) => path.replace(new RegExp(`^${prefix}`), ""),
+      // Bearer injection happens in the awaited auth middleware (see auth-middleware.ts);
+      // Vite forwards incoming request headers to the upstream. Here we only surface a
+      // one-time hint when the upstream rejects our token.
+      configure: (proxy) => {
+        let warned = false;
+        proxy.on("proxyRes", (proxyRes) => {
+          if (proxyRes.statusCode === 401 && !warned) {
+            warned = true;
+            console.warn(
+              "  [lessly-app-dev] upstream returned 401 Unauthorized. Your session may be revoked server-side. Delete ~/.lessly/credentials.json and re-run dev to re-login."
+            );
+          }
+        });
+      }
+    }
+  };
+}
+
+// src/config-inject.ts
+function productIdMissingWarning() {
+  return [
+    "  [lessly-app-dev] WARNING: VITE_PRODUCT_ID is not set.",
+    "  \u2022 Set it in .env.local:  VITE_PRODUCT_ID=<your product id>",
+    "  \u2022 Find the id in the Lessly workspace URL (\u2026/products/<id>) or ask your workspace admin.",
+    "  \u2022 Safe to ignore in composed dev (dev:federation / dev:shell): the shell supplies the",
+    "    product id at runtime. Standalone without it renders a BootPage."
+  ].join("\n");
+}
+function buildDefine(args) {
+  const define = {
+    "import.meta.env.VITE_LESSLY_BASE_URL": JSON.stringify(args.proxyPath)
+  };
+  if (args.productId) define["import.meta.env.VITE_PRODUCT_ID"] = JSON.stringify(args.productId);
+  return define;
+}
+
+// src/credentials-store.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function credentialsPath(home = homedir()) {
+  return join(home, ".lessly", "credentials.json");
+}
+function readCredentials(home = homedir()) {
+  const path = credentialsPath(home);
+  if (!existsSync(path)) return { tokens: {} };
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return { tokens: {} };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `~/.lessly/credentials.json is corrupted and could not be parsed. Delete it (rm ${path}) and run dev again to re-authenticate.`
+    );
+  }
+  if (!parsed || typeof parsed !== "object") return { tokens: {} };
+  const creds = parsed;
+  creds.tokens ??= {};
+  return creds;
+}
+function loadAccessToken(home, profile) {
+  return readCredentials(home).tokens[profile];
+}
+function loadRefreshToken(home, profile) {
+  return readCredentials(home).refresh?.[profile];
+}
+function saveTokens(home, profile, t) {
+  const creds = readCredentials(home);
+  creds.tokens[profile] = t.accessToken;
+  if (t.refreshToken) (creds.refresh ??= {})[profile] = t.refreshToken;
+  mkdirSync(join(home, ".lessly"), { recursive: true });
+  const path = credentialsPath(home);
+  writeFileSync(path, JSON.stringify(creds, null, 2), { mode: 384 });
+  chmodSync(path, 384);
+}
+
+// src/jwt.ts
+function decodeJwtPayload(token) {
+  try {
+    const part = token.split(".")[1];
+    if (!part) return void 0;
+    return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function isExpired(token, now = Date.now(), skewSeconds = 60) {
+  const p = decodeJwtPayload(token);
+  const exp = typeof p?.exp === "number" ? p.exp : void 0;
+  if (exp === void 0) return true;
+  return (exp - skewSeconds) * 1e3 <= now;
+}
+
+// src/refresh-lock.ts
+import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeSync } from "fs";
+import { hostname } from "os";
+import { join as join2 } from "path";
+import { randomUUID } from "crypto";
+function defaultIsAlive(holder) {
+  if (!holder.host || holder.host !== hostname()) return true;
+  if (typeof holder.pid !== "number") return true;
+  try {
+    process.kill(holder.pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function readHolder(lockPath) {
+  try {
+    const parsed = JSON.parse(readFileSync2(lockPath, "utf8"));
+    if (parsed && typeof parsed === "object" && typeof parsed.owner === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+async function withRefreshLock(home, fn, opts = {}) {
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const staleMs = opts.staleMs ?? 3e4;
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const pollMs = opts.pollMs ?? 100;
+  const isAlive = opts.isAlive ?? defaultIsAlive;
+  const dir = join2(home, ".lessly");
+  mkdirSync2(dir, { recursive: true });
+  const lockPath = join2(dir, "refresh.lock");
+  const deadline = now() + timeoutMs;
+  const owner = randomUUID();
+  const meta = JSON.stringify({ owner, pid: process.pid, host: hostname() });
+  for (; ; ) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      writeSync(fd, meta);
+      closeSync(fd);
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      let age;
+      try {
+        age = now() - statSync(lockPath).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (age > staleMs) {
+        const holder = readHolder(lockPath);
+        const dead = holder ? !isAlive(holder) : true;
+        if (dead) {
+          const claim = `${lockPath}.reclaim.${owner}`;
+          try {
+            renameSync(lockPath, claim);
+          } catch {
+            continue;
+          }
+          const claimed = readHolder(claim);
+          if (claimed && isAlive(claimed)) {
+            try {
+              const fd = openSync(lockPath, "wx");
+              writeSync(fd, JSON.stringify(claimed));
+              closeSync(fd);
+            } catch {
+            }
+            try {
+              unlinkSync(claim);
+            } catch {
+            }
+          } else {
+            try {
+              unlinkSync(claim);
+            } catch {
+            }
+            continue;
+          }
+        }
+      }
+      if (now() >= deadline) {
+        throw new Error(
+          `timed out waiting for the Lessly refresh lock; another process is still refreshing the token. Retry, or if it is stuck delete ${lockPath}.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try {
+      if (readHolder(lockPath)?.owner === owner) unlinkSync(lockPath);
+    } catch {
+    }
+  }
+}
+
+// src/token.ts
+function createTokenProvider(args) {
+  let inflight = null;
+  let cached = null;
+  async function resolve() {
+    if (cached && !isExpired(cached)) return cached;
+    const stored = loadAccessToken(args.home, args.profile);
+    if (stored && !isExpired(stored)) return stored;
+    const refreshTok = loadRefreshToken(args.home, args.profile);
+    if (refreshTok) {
+      const withLock = args.withLock ?? withRefreshLock;
+      try {
+        return cached = await withLock(args.home, async () => {
+          const fresh = loadAccessToken(args.home, args.profile);
+          if (fresh && !isExpired(fresh)) return fresh;
+          const rt = loadRefreshToken(args.home, args.profile) ?? refreshTok;
+          return await args.refresh(rt);
+        });
+      } catch {
+      }
+    }
+    if (args.apiKey) return cached = await args.apiKey();
+    return cached = await args.device();
+  }
+  return {
+    get() {
+      return inflight ??= resolve().finally(() => {
+        inflight = null;
+      });
+    }
+  };
+}
+
+// src/refresh.ts
+var CLIENT_ID = "lessly-cli";
+async function refreshAccessToken(args) {
+  const res = await args.post(`${args.authServer}/oauth/token`, {
+    grant_type: "refresh_token",
+    refresh_token: args.refreshToken,
+    client_id: CLIENT_ID
+  });
+  if (res.status < 200 || res.status >= 300 || !res.body?.access_token) {
+    const err = res.body?.error ?? `HTTP ${res.status}`;
+    throw new Error(`token refresh failed: ${err}`);
+  }
+  saveTokens(args.home, args.profile, {
+    accessToken: res.body.access_token,
+    refreshToken: res.body.refresh_token ?? args.refreshToken
+  });
+  return res.body.access_token;
+}
+
+// src/device.ts
+var CLIENT_ID2 = "lessly-cli";
+var DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+async function runDeviceLogin(args) {
+  const { authServer, deps, io } = args;
+  const authRes = await deps.post(`${authServer}/oauth/device_authorization`, { client_id: CLIENT_ID2 });
+  if (authRes.status < 200 || authRes.status >= 300) {
+    throw new Error(`device authorization failed (${authRes.status})`);
+  }
+  const auth = authRes.body;
+  io.print(`
+  To sign in, open ${auth.verification_uri} and enter code: ${auth.user_code}`);
+  if (auth.verification_uri_complete) io.print(`  Or open: ${auth.verification_uri_complete}`);
+  io.print("  Waiting for authorization\u2026\n");
+  let interval = Math.max(1, auth.interval || 5);
+  const expiresIn = Number.isFinite(auth.expires_in) && auth.expires_in > 0 ? auth.expires_in : 600;
+  const deadline = deps.now() + expiresIn * 1e3;
+  for (; ; ) {
+    await deps.sleep(interval * 1e3);
+    if (deps.now() >= deadline) throw new Error("device login expired; run dev again");
+    const res = await deps.post(`${authServer}/oauth/token`, {
+      grant_type: DEVICE_GRANT,
+      device_code: auth.device_code,
+      client_id: CLIENT_ID2
+    });
+    if (res.status >= 200 && res.status < 300 && res.body?.access_token) {
+      saveTokens(args.home, args.profile, { accessToken: res.body.access_token, refreshToken: res.body.refresh_token });
+      return res.body.access_token;
+    }
+    const error = res.body?.error;
+    if (error === "authorization_pending") continue;
+    if (error === "slow_down") {
+      interval += 5;
+      continue;
+    }
+    if (error === "expired_token") throw new Error("device login expired; run dev again");
+    if (error === "access_denied") throw new Error("device login was denied");
+    throw new Error(`device login failed: ${error ?? `HTTP ${res.status}`}`);
+  }
+}
+function defaultDeviceDeps() {
+  return {
+    post: async (url, form) => {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: new URLSearchParams(form).toString()
+      });
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        body = void 0;
+      }
+      return { status: res.status, body };
+    },
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now()
+  };
+}
+
+// src/api-key.ts
+async function resolveApiKeyToken(args) {
+  if (!args.apiKey) throw new Error("DEV_API_KEY is empty");
+  const fetchFn = args.fetchFn ?? fetch;
+  const base = args.authServer.replace(/\/+$/, "");
+  const apiBase = base.endsWith("/api/v1") ? base : `${base}/api/v1`;
+  const res = await fetchFn(`${apiBase}/api-keys/exchange`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${args.apiKey}` },
+    body: JSON.stringify({})
+  });
+  if (!res.ok) {
+    let body = {};
+    try {
+      body = await res.json();
+    } catch {
+    }
+    throw new Error(`DEV_API_KEY exchange failed (${res.status}): ${body.error ?? body.message ?? "unknown error"}`);
+  }
+  const envelope = await res.json();
+  return envelope.data.idToken;
+}
+
+// src/composed-dev.ts
+function resolveShellDevOrigin(processEnv = process.env) {
+  return processEnv.SHELL_DEV_ORIGIN ?? "http://localhost:5173";
+}
+function shellOverrideMessage(slug, origin) {
+  return [
+    "  To load this App inside the Workspace shell dev server, run this in the",
+    "  shell browser console (C3 contract):",
+    "",
+    `    localStorage.setItem('lessly:dev-remote', '${slug}=${origin}')`,
+    "",
+    "  then reload the shell."
+  ].join("\n");
+}
+
+// src/mf-manifest.ts
+var MANIFEST_PATH = "/mf-manifest.json";
+function mfManifestMiddleware(getBase) {
+  return (req, _res, next) => {
+    const [path, query] = (req.url ?? "").split("?");
+    if (req.method !== "GET" || path !== MANIFEST_PATH) {
+      next();
+      return;
+    }
+    const base = getBase().replace(/\/+$/, "");
+    if (base) {
+      req.url = `${base}${MANIFEST_PATH}${query ? `?${query}` : ""}`;
+    }
+    next();
+  };
+}
+
+// src/auth-middleware.ts
+function createAuthMiddleware(args) {
+  const boundary = new RegExp(`^${args.proxyPath}(?:[/?]|$)`);
+  return (req, res, next) => {
+    const url = req.url ?? "";
+    if (!boundary.test(url)) return next();
+    if (req.headers["sec-fetch-site"] === "cross-site") {
+      res.statusCode = 403;
+      res.end("cross-site requests to the Lessly dev proxy are not allowed");
+      return;
+    }
+    args.token.get().then(
+      (t) => {
+        req.headers.authorization = `Bearer ${t}`;
+        next();
+      },
+      (err) => next(err)
+    );
+  };
+}
+
+// src/index.ts
+import { homedir as homedir2 } from "os";
+var PROXY_PATH = "/lessly-api";
+function lesslyAppDev(options = {}, deps = {}) {
+  const homedirFn = deps.homedir ?? homedir2;
+  const devDeps = defaultDeviceDeps();
+  const post = devDeps.post;
+  let token;
+  let resolvedEnv;
+  let productId;
+  let slug = "your-app";
+  function buildToken(env, apiKeyEnv) {
+    if (deps.createToken) return deps.createToken({ env, apiKeyEnv });
+    const home = homedirFn();
+    return createTokenProvider({
+      home,
+      profile: env.profile,
+      authServer: env.authServer,
+      refresh: (rt) => refreshAccessToken({ authServer: env.authServer, refreshToken: rt, home, profile: env.profile, post }),
+      device: () => runDeviceLogin({ authServer: env.authServer, home, profile: env.profile, deps: devDeps, io: { print: (m) => console.log(m) } }),
+      apiKey: apiKeyEnv ? () => resolveApiKeyToken({ apiKey: apiKeyEnv, authServer: env.authServer }) : void 0
+    });
+  }
+  return {
+    name: "lessly-app-dev",
+    config(config, envInfo) {
+      if (envInfo.command !== "serve") return void 0;
+      const root = config.root ?? process.cwd();
+      const fileEnv = loadEnv(envInfo.mode, root, "");
+      resolvedEnv = resolveEnv({ env: options.env, apiUrl: options.apiUrl, processEnv: fileEnv });
+      productId = fileEnv.VITE_PRODUCT_ID;
+      slug = fileEnv.VITE_PRODUCT_SLUG ?? "your-app";
+      token = buildToken(resolvedEnv, fileEnv.DEV_API_KEY);
+      return {
+        server: { proxy: buildProxyConfig({ apiUrl: resolvedEnv.apiUrl, proxyPath: PROXY_PATH }) },
+        define: buildDefine({ productId, proxyPath: PROXY_PATH })
+      };
+    },
+    configureServer(server) {
+      if (token) server.middlewares.use(createAuthMiddleware({ proxyPath: PROXY_PATH, token }));
+      server.middlewares.use(mfManifestMiddleware(() => server.config.base));
+      server.httpServer?.once("listening", () => {
+        const env = resolvedEnv;
+        console.log(`
+  [lessly-app-dev] proxying ${PROXY_PATH} \u2192 ${env.apiUrl} (${env.name})`);
+        if (!productId) console.warn(productIdMissingWarning());
+        console.log(shellOverrideMessage(slug, resolveShellDevOrigin()));
+      });
+    }
+  };
+}
+export {
+  lesslyAppDev,
+  resolveShellDevOrigin
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lessly/app-dev",
+  "version": "0.1.0",
+  "description": "Vite plugin for local development of Lessly Apps",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist/**"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": { "vite": ">=7" },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.18",
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+}