htmlship 0.1.5 → 0.3.0

package/README.md

@@ -16,9 +16,21 @@ npx htmlship delete <slug>
 npx htmlship list-mine
 ```
 
+## Deploy built apps
+
+Build a modern frontend project (React/Vite/etc.) and publish the compiled app as one self-contained page:
+
+```bash
+npx htmlship deploy ./my-app           # detect build script, build, inline, publish
+npx htmlship deploy --dry-run          # build + inline without publishing
+npx htmlship deploy --build-cmd "vite build" --out dist
+```
+
+The build runs **locally on your machine** (npm/pnpm/yarn/bun, auto-detected) — never on the server. The output is inlined into a single HTML file (≤ 10 MB) and published with relaxed sandboxing, so the app's JavaScript runs in an isolated, opaque origin (no cookies, no same-origin access, no network egress, no `eval`). The same flow is available to agents through the `deploy_project` MCP tool.
+
 ## MCP server
 
-`htmlship mcp` starts a stdio MCP server with three tools: `publish_html` (with optional `password`), `fetch_html`, `update_html`.
+`htmlship mcp` starts a stdio MCP server with four tools: `publish_html` (with optional `password`), `deploy_project` (build a local project and publish the compiled app), `fetch_html`, `update_html`.
 
 ### Claude Desktop / Claude Code / Cursor
 

package/dist/cli.js

@@ -51,22 +51,418 @@ var init_errors = __esm({
   }
 });
 
+// src/build.ts
+import { spawnSync } from "child_process";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "path";
+function detectPackageManager(dir) {
+  for (const [file, pm] of LOCKFILES) {
+    if (existsSync(join(dir, file))) return pm;
+  }
+  return "npm";
+}
+function detectProject(dir, buildCmdOverride) {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath)) {
+    throw new HTMLShipError(`no package.json found in ${dir}`);
+  }
+  let scripts = {};
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (pkg && typeof pkg === "object" && "scripts" in pkg) {
+      const s = pkg.scripts;
+      if (s && typeof s === "object") scripts = s;
+    }
+  } catch (err) {
+    throw new HTMLShipError(`failed to read package.json: ${err.message}`);
+  }
+  const pm = detectPackageManager(dir);
+  if (buildCmdOverride) {
+    return { dir, buildScript: "", packageManager: pm };
+  }
+  const buildScript = scripts["build"] ? "build" : scripts["build:prod"] ? "build:prod" : null;
+  if (!buildScript) {
+    throw new HTMLShipError(
+      'no "build" or "build:prod" script in package.json (use --build-cmd to specify one)'
+    );
+  }
+  return { dir, buildScript, packageManager: pm };
+}
+function buildCommand(pm, script) {
+  return pm === "yarn" ? `yarn ${script}` : `${pm} run ${script}`;
+}
+function installCommand(pm) {
+  return `${pm} install`;
+}
+function runBuild(project, opts = {}) {
+  const log = opts.log ?? (() => {
+  });
+  const timeout = opts.timeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS;
+  if (opts.install) {
+    exec(installCommand(project.packageManager), project.dir, timeout, log);
+  }
+  const cmd = opts.buildCmd ?? buildCommand(project.packageManager, project.buildScript);
+  exec(cmd, project.dir, timeout, log);
+}
+function exec(command, cwd, timeout, log) {
+  log(`$ ${command}`);
+  const r = spawnSync(command, { cwd, stdio: "inherit", timeout, shell: true });
+  if (r.error) {
+    const code = r.error.code;
+    if (code === "ENOENT") {
+      throw new HTMLShipError(`build failed: \`${command}\` \u2014 command not found`);
+    }
+    throw new HTMLShipError(`build failed: ${r.error.message}`);
+  }
+  if (r.signal === "SIGTERM") {
+    throw new HTMLShipError(`build timed out after ${Math.round(timeout / 1e3)}s: \`${command}\``);
+  }
+  if (typeof r.status === "number" && r.status !== 0) {
+    throw new HTMLShipError(`build exited with code ${r.status}: \`${command}\``);
+  }
+}
+function looksLikeNextJs(dir) {
+  if (existsSync(join(dir, ".next"))) return true;
+  return ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"].some(
+    (f) => existsSync(join(dir, f))
+  );
+}
+function noOutputMessage(dir) {
+  const base = `no build output found (looked for ${OUTPUT_DIR_CANDIDATES.map((c) => `${c}/`).join(", ")}; use --out to specify)`;
+  if (looksLikeNextJs(dir)) {
+    return `${base}.
+This looks like a Next.js app: \`next build\` writes a server build to .next/, which is not statically hostable. Add \`output: "export"\` to your next.config to emit a static out/ folder, then re-run. Note: deploy inlines a single-page static app \u2014 server-rendered or multi-route Next.js sites are not supported.`;
+  }
+  return base;
+}
+function resolveOutputDir(dir, override) {
+  const candidates = override ? [override] : OUTPUT_DIR_CANDIDATES;
+  for (const c of candidates) {
+    const p = isAbsolute(c) ? c : join(dir, c);
+    if (existsSync(p) && statSync(p).isDirectory()) return p;
+  }
+  throw new HTMLShipError(
+    override ? `build output dir not found: ${override}` : noOutputMessage(dir)
+  );
+}
+function isNextServerBuild(dir) {
+  return existsSync(join(dir, "BUILD_ID")) || existsSync(join(dir, "server")) && existsSync(join(dir, "static"));
+}
+function noEntryMessage(outDir, htmls) {
+  if (isNextServerBuild(outDir)) {
+    return `no static HTML entry in ${outDir} \u2014 this looks like a Next.js server build, not a static site. Set \`output: "export"\` in your next.config (this emits a fully static out/ folder); changing distDir alone only renames the server build. Note: apps that use middleware or server rendering cannot be statically exported.`;
+  }
+  if (htmls.length > 1) {
+    return `no index.html in ${outDir}, but found ${htmls.length} HTML files (${htmls.slice(0, 4).join(", ")}${htmls.length > 4 ? ", \u2026" : ""}). deploy ships a single page \u2014 pass --entry <file> to choose one.`;
+  }
+  return `entry HTML not found in ${outDir} (looked for index.html); pass --entry <file> to specify it.`;
+}
+function resolveEntry(outDir, entryOverride) {
+  if (entryOverride) {
+    const p = join(outDir, entryOverride);
+    if (existsSync(p)) return p;
+    throw new HTMLShipError(`entry HTML not found: ${p}`);
+  }
+  for (const name of ["index.html", "200.html", "index.htm"]) {
+    const p = join(outDir, name);
+    if (existsSync(p)) return p;
+  }
+  let htmls = [];
+  try {
+    htmls = readdirSync(outDir).filter((f) => f.toLowerCase().endsWith(".html"));
+  } catch {
+    htmls = [];
+  }
+  if (htmls.length === 1) return join(outDir, htmls[0]);
+  throw new HTMLShipError(noEntryMessage(outDir, htmls));
+}
+function mimeFor(p) {
+  return MIME[extname(p).toLowerCase()] ?? "application/octet-stream";
+}
+function isLocalRef(ref) {
+  return ref.length > 0 && !/^(https?:)?\/\//i.test(ref) && !ref.startsWith("data:") && !ref.startsWith("#") && !ref.startsWith("mailto:") && !ref.startsWith("blob:");
+}
+function attr(tag, name) {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)'|([^\\s>]+))`, "i"));
+  if (!m) return null;
+  return m[2] ?? m[3] ?? m[4] ?? null;
+}
+function resolveLocal(root, baseDir, ref) {
+  let clean = ref.split("#")[0].split("?")[0];
+  if (!clean) return null;
+  let base = baseDir;
+  if (clean.startsWith("/")) {
+    base = root;
+    clean = clean.replace(/^\/+/, "");
+  }
+  let abs;
+  try {
+    abs = resolve(base, decodeURIComponent(clean));
+  } catch {
+    return null;
+  }
+  const rel = relative(root, abs);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  if (!existsSync(abs) || !statSync(abs).isFile()) return null;
+  return abs;
+}
+function dataUri(file) {
+  return `data:${mimeFor(file)};base64,${readFileSync(file).toString("base64")}`;
+}
+function inlineCssUrls(root, cssDir, css, warnings) {
+  return css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/gi, (whole, _q, ref) => {
+    if (!isLocalRef(ref)) return whole;
+    const file = resolveLocal(root, cssDir, ref);
+    if (!file) {
+      warnings.push(`unresolved css asset: ${ref}`);
+      return whole;
+    }
+    return `url(${dataUri(file)})`;
+  });
+}
+function inlineHtml(root, htmlFile) {
+  if (!existsSync(htmlFile)) {
+    throw new HTMLShipError(`entry HTML not found: ${htmlFile}`);
+  }
+  const htmlDir = dirname(htmlFile);
+  const warnings = [];
+  let html = readFileSync(htmlFile, "utf8");
+  const localFile = (ref) => {
+    if (!isLocalRef(ref)) return null;
+    const file = resolveLocal(root, htmlDir, ref);
+    if (!file) {
+      warnings.push(`unresolved asset: ${ref}`);
+      return null;
+    }
+    return file;
+  };
+  html = html.replace(/<link\b[^>]*>/gi, (tag) => {
+    const rel = attr(tag, "rel")?.toLowerCase() ?? "";
+    const href = attr(tag, "href");
+    if (!href) return tag;
+    if (rel === "stylesheet") {
+      const file = localFile(href);
+      if (!file) return tag;
+      const css = inlineCssUrls(root, dirname(file), readFileSync(file, "utf8"), warnings);
+      return `<style>${css}</style>`;
+    }
+    if (rel === "modulepreload" || rel === "preload" || rel === "prefetch") {
+      return isLocalRef(href) ? "" : tag;
+    }
+    if (rel === "icon" || rel === "shortcut icon" || rel === "apple-touch-icon") {
+      const file = localFile(href);
+      return file ? tag.replace(href, dataUri(file)) : tag;
+    }
+    return tag;
+  });
+  html = html.replace(/<script\b([^>]*)>\s*<\/script>/gi, (tag, attrs) => {
+    const src = attr(tag, "src");
+    if (!src) return tag;
+    const file = localFile(src);
+    if (!file) return tag;
+    const js = readFileSync(file, "utf8").replace(/<\/script/gi, "<\\/script");
+    const typeAttr = /\btype\s*=\s*["']module["']/i.test(attrs) ? ' type="module"' : "";
+    return `<script${typeAttr}>${js}</script>`;
+  });
+  html = html.replace(/<img\b[^>]*>/gi, (tag) => {
+    const src = attr(tag, "src");
+    if (!src || !isLocalRef(src)) return tag;
+    const file = localFile(src);
+    return file ? tag.replace(src, dataUri(file)) : tag;
+  });
+  return { html, warnings, bytes: Buffer.byteLength(html, "utf8") };
+}
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+function isNextProject(dir) {
+  if (NEXT_CONFIGS.some((f) => existsSync(join(dir, f)))) return true;
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return Boolean(pkg.dependencies?.["next"] || pkg.devDependencies?.["next"]);
+  } catch {
+    return false;
+  }
+}
+function injectNextBase(dir) {
+  const existing = NEXT_CONFIGS.find((f) => existsSync(join(dir, f)));
+  if (existing && existing.endsWith(".ts")) {
+    throw new HTMLShipError(
+      `Next .ts config isn't auto-configured yet. Temporarily set basePath and assetPrefix to "${SITE_BASE_PLACEHOLDER}" and output: "export" in next.config.ts, or convert it to next.config.mjs, then re-run.`
+    );
+  }
+  const wrapper = join(dir, "next.config.mjs");
+  const base = SITE_BASE_PLACEHOLDER;
+  if (!existing) {
+    writeFileSync(
+      wrapper,
+      `export default { output: 'export', basePath: '${base}', assetPrefix: '${base}', images: { unoptimized: true }, trailingSlash: true };
+`
+    );
+    return () => {
+      try {
+        unlinkSync(wrapper);
+      } catch {
+      }
+    };
+  }
+  const ext = extname(existing);
+  const backupName = `next.config.__hsorig__${ext}`;
+  renameSync(join(dir, existing), join(dir, backupName));
+  writeFileSync(
+    wrapper,
+    `import orig from './${backupName}';
+const base = '${base}';
+const over = { output: 'export', basePath: base, assetPrefix: base, images: { ...(typeof orig === 'object' && orig ? orig.images : {}), unoptimized: true }, trailingSlash: true };
+export default typeof orig === 'function' ? ((...a) => ({ ...orig(...a), ...over })) : { ...orig, ...over };
+`
+  );
+  return () => {
+    try {
+      unlinkSync(wrapper);
+    } catch {
+    }
+    try {
+      renameSync(join(dir, backupName), join(dir, existing));
+    } catch {
+    }
+  };
+}
+function packageSite(outDir, maxBytes = 10 * 1024 * 1024) {
+  const files = [];
+  let total = 0;
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) {
+        const buf = readFileSync(full);
+        total += buf.length;
+        if (total > maxBytes) {
+          throw new HTMLShipError(`site exceeds the ${maxBytes / (1024 * 1024)} MB limit`);
+        }
+        files.push({ path: relative(outDir, full).split(sep).join("/"), content: buf.toString("base64") });
+      }
+    }
+  };
+  walk(outDir);
+  return { files, bytes: total };
+}
+function buildAndPackageSite(dir, opts = {}) {
+  const log = opts.log ?? (() => {
+  });
+  const project = detectProject(dir, opts.buildCmd);
+  const next = !opts.buildCmd && isNextProject(dir);
+  log(`project:   ${dir}`);
+  log(`pkg mgr:   ${project.packageManager}`);
+  log(`framework: ${next ? "next.js (static export)" : "multi-file"}`);
+  const cleanup = next ? injectNextBase(dir) : () => {
+  };
+  try {
+    if (next) log(`base:      ${SITE_BASE_PLACEHOLDER} (injected for path hosting)`);
+    runBuild(project, {
+      install: opts.install,
+      buildCmd: opts.buildCmd,
+      timeoutMs: opts.timeoutMs,
+      log
+    });
+  } finally {
+    cleanup();
+  }
+  const outDir = resolveOutputDir(dir, opts.out);
+  const entryAbs = resolveEntry(outDir, opts.entry);
+  const entry = relative(outDir, entryAbs).split(sep).join("/");
+  const { files, bytes } = packageSite(outDir);
+  log(`output:    ${outDir}`);
+  log(`packaged:  ${files.length} files, ${formatBytes(bytes)}`);
+  return { files, bytes, entry, framework: next ? "next" : "multi-file" };
+}
+function buildAndInline(dir, opts = {}) {
+  const log = opts.log ?? (() => {
+  });
+  const project = detectProject(dir, opts.buildCmd);
+  log(`project:   ${dir}`);
+  log(`pkg mgr:   ${project.packageManager}`);
+  log(`build:     ${opts.buildCmd ?? buildCommand(project.packageManager, project.buildScript)}`);
+  runBuild(project, {
+    install: opts.install,
+    buildCmd: opts.buildCmd,
+    timeoutMs: opts.timeoutMs,
+    log
+  });
+  const outDir = resolveOutputDir(dir, opts.out);
+  const entry = resolveEntry(outDir, opts.entry);
+  const result = inlineHtml(outDir, entry);
+  log(`output:    ${outDir}`);
+  log(`inlined:   ${formatBytes(result.bytes)} single HTML`);
+  for (const w of result.warnings) log(`warning:   ${w}`);
+  return result;
+}
+var SITE_BASE_PLACEHOLDER, NEXT_CONFIGS, LOCKFILES, DEFAULT_BUILD_TIMEOUT_MS, OUTPUT_DIR_CANDIDATES, MIME;
+var init_build = __esm({
+  "src/build.ts"() {
+    "use strict";
+    init_errors();
+    SITE_BASE_PLACEHOLDER = "/__htmlship_base__";
+    NEXT_CONFIGS = ["next.config.mjs", "next.config.js", "next.config.cjs", "next.config.ts"];
+    LOCKFILES = [
+      ["pnpm-lock.yaml", "pnpm"],
+      ["yarn.lock", "yarn"],
+      ["bun.lockb", "bun"],
+      ["bun.lock", "bun"],
+      ["package-lock.json", "npm"]
+    ];
+    DEFAULT_BUILD_TIMEOUT_MS = 5 * 6e4;
+    OUTPUT_DIR_CANDIDATES = ["dist", "build", "out"];
+    MIME = {
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".svg": "image/svg+xml",
+      ".webp": "image/webp",
+      ".avif": "image/avif",
+      ".ico": "image/x-icon",
+      ".woff": "font/woff",
+      ".woff2": "font/woff2",
+      ".ttf": "font/ttf",
+      ".otf": "font/otf",
+      ".css": "text/css",
+      ".js": "text/javascript",
+      ".mjs": "text/javascript",
+      ".json": "application/json"
+    };
+  }
+});
+
 // src/version.ts
 var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.1.5";
+    VERSION = "0.3.0";
   }
 });
 
 // src/client.ts
-var DEFAULT_API_URL, HTMLShipClient;
+var MAX_PAYLOAD_BYTES, DEFAULT_API_URL, HTMLShipClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
+    init_build();
     init_errors();
     init_version();
+    MAX_PAYLOAD_BYTES = 10 * 1024 * 1024;
     DEFAULT_API_URL = "https://api.htmlship.com";
     HTMLShipClient = class {
       baseUrl;
@@ -92,6 +488,59 @@ var init_client = __esm({
         if (options.parentSlug != null) body["parent_slug"] = options.parentSlug;
         return await this.request("POST", "/api/v1/pages", { body });
       }
+      /**
+       * Build a local frontend project, inline its output into one self-contained
+       * HTML document, and publish it as a relaxed (sandboxed-script) page. The
+       * build runs on this machine — never on the server.
+       */
+      async deploy(projectDir, options = {}) {
+        const { html, bytes } = buildAndInline(projectDir, {
+          buildCmd: options.buildCmd,
+          out: options.out,
+          entry: options.entry,
+          install: options.install
+        });
+        if (bytes > MAX_PAYLOAD_BYTES) {
+          throw new HTMLShipError(`inlined page is ${bytes} bytes, exceeds the 10 MB limit`);
+        }
+        return await this.publish(html, {
+          title: options.title ?? null,
+          password: options.password ?? null,
+          expiresIn: options.expiresIn ?? null,
+          sandboxMode: "relaxed"
+        });
+      }
+      /** Upload a multi-file static site (built locally) and get its URL. */
+      async deploySite(files, options = {}) {
+        const body = { files };
+        if (options.entry) body["entry"] = options.entry;
+        if (options.title != null) body["title"] = options.title;
+        if (options.password != null) body["password"] = options.password;
+        if (options.expiresIn != null) body["expires_in"] = options.expiresIn;
+        return await this.request("POST", "/api/v1/sites", { body });
+      }
+      /**
+       * Build a local project and deploy it, auto-choosing single-file inlining
+       * (SPA) vs. multi-file site hosting (Next.js, or when options.site is set).
+       */
+      async deployProject(projectDir, options = {}) {
+        const useSite = options.singleFile ? false : options.site || isNextProject(projectDir);
+        if (useSite) {
+          const { files, entry } = buildAndPackageSite(projectDir, {
+            buildCmd: options.buildCmd,
+            out: options.out,
+            entry: options.entry,
+            install: options.install
+          });
+          return await this.deploySite(files, {
+            entry,
+            title: options.title ?? null,
+            password: options.password ?? null,
+            expiresIn: options.expiresIn ?? null
+          });
+        }
+        return await this.deploy(projectDir, options);
+      }
       async get(slug) {
         return await this.request("GET", `/api/v1/pages/${encodeURIComponent(slug)}`);
       }
@@ -240,6 +689,54 @@ function buildMcpServer(client) {
       }
     }
   );
+  server.registerTool(
+    "deploy_project",
+    {
+      description: "Build a local frontend project (npm/pnpm/yarn/bun) and deploy the compiled app. Runs the project's build script ON THIS MACHINE. Single-page apps (Vite/CRA) are inlined into one self-contained, script-enabled page; multi-file sites (Next.js static export, auto-detected) are hosted at view.htmlship.com/{slug}/. Both run with relaxed sandboxing so their JS runs in an isolated origin. The owner_key returned is the only credential to update or delete this later \u2014 save it.",
+      inputSchema: {
+        dir: z.string().describe("Path to the project directory (must contain package.json)."),
+        build_cmd: z.string().optional().describe("Override the build command (default: detected build/build:prod script)."),
+        out: z.string().optional().describe("Build output directory (default: auto-detect dist/, build/, out/)."),
+        site: z.boolean().optional().describe("Force multi-file site hosting (auto-detected for Next.js)."),
+        install: z.boolean().optional().describe("Run dependency install before building."),
+        title: z.string().optional().describe("Optional human-readable title."),
+        password: z.string().optional().describe("Optional password required before viewing."),
+        expires_in: z.number().int().min(1).max(60 * 24 * 7).optional().describe("Optional TTL in minutes (1\u201310080, i.e. up to 7 days).")
+      }
+    },
+    async ({ dir, build_cmd, out, site, install, title, password, expires_in }) => {
+      try {
+        const page = await c.deployProject(dir, {
+          buildCmd: build_cmd ?? void 0,
+          out: out ?? void 0,
+          site: site ?? void 0,
+          install: install ?? void 0,
+          title: title ?? null,
+          password: password ?? null,
+          expiresIn: expires_in ?? null
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  url: page.url,
+                  slug: page.slug,
+                  owner_key: page.owner_key,
+                  expires_at: page.expires_at
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        return errorResult("deploy_project", err);
+      }
+    }
+  );
   server.registerTool(
     "fetch_html",
     {
@@ -328,16 +825,16 @@ init_errors();
 import { createInterface } from "readline/promises";
 
 // src/keystore.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2, chmodSync } from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { join as join2 } from "path";
 function createKeyStore(overrideDir) {
-  const dir = overrideDir ?? process.env["HTMLSHIP_KEYS_DIR"] ?? join(homedir(), ".htmlship");
-  const file = join(dir, "keys.json");
+  const dir = overrideDir ?? process.env["HTMLSHIP_KEYS_DIR"] ?? join2(homedir(), ".htmlship");
+  const file = join2(dir, "keys.json");
   function load() {
-    if (!existsSync(file)) return {};
+    if (!existsSync2(file)) return {};
     try {
-      const text = readFileSync(file, "utf8");
+      const text = readFileSync2(file, "utf8");
       const parsed = JSON.parse(text);
       if (parsed && typeof parsed === "object") return parsed;
       return {};
@@ -346,12 +843,12 @@ function createKeyStore(overrideDir) {
     }
   }
   function save(data) {
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    if (!existsSync2(dir)) mkdirSync(dir, { recursive: true });
     const sorted = {};
     for (const key of Object.keys(data).sort()) {
       sorted[key] = data[key];
     }
-    writeFileSync(file, JSON.stringify(sorted, null, 2), "utf8");
+    writeFileSync2(file, JSON.stringify(sorted, null, 2), "utf8");
     try {
       chmodSync(file, 384);
     } catch {
@@ -420,6 +917,146 @@ function registerDelete(program) {
   });
 }
 
+// src/commands/deploy.ts
+init_build();
+init_client();
+init_errors();
+import { resolve as resolve2 } from "path";
+
+// src/io.ts
+import { readFileSync as readFileSync3 } from "fs";
+function readHtmlFromSource(source, fileFlag) {
+  if (fileFlag) {
+    return readFileSync3(fileFlag, "utf8");
+  }
+  if (source === "-" || source === void 0) {
+    if (source === void 0 && process.stdin.isTTY) {
+      throw new CliUsageError("Provide a file path or pipe HTML on stdin.");
+    }
+    return readStdinSync();
+  }
+  return readFileSync3(source, "utf8");
+}
+var CliUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+};
+function readStdinSync() {
+  try {
+    return readFileSync3(0, "utf8");
+  } catch (err) {
+    throw new CliUsageError(`failed to read stdin: ${err.message}`);
+  }
+}
+async function tryClipboardCopy(text) {
+  try {
+    const mod = await import("clipboardy");
+    await mod.default.write(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/deploy.ts
+var MAX_INLINE_BYTES = 10 * 1024 * 1024;
+function registerDeploy(program) {
+  program.command("deploy").description(
+    "Build a frontend project and deploy it \u2014 a single-page app as one inlined page, or a multi-file site (Next.js, etc.) at view.htmlship.com/{slug}/."
+  ).argument("[dir]", "project directory (default: current directory)", ".").option("--build-cmd <cmd>", "Override the build command (default: detected from package.json)").option("--out <dir>", "Build output directory (default: auto-detect dist/, build/, out/)").option("--entry <file>", "Entry HTML within the output dir (default: index.html)").option("--site", "Force multi-file site hosting (auto-detected for Next.js)").option("--single-file", "Force single-file inlining (one self-contained page)").option("--install", "Run dependency install before building").option("--dry-run", "Build, but report a summary instead of publishing").option("--title <title>", "Optional title").option("--password <password>", "Password-protect the page").option("--expires-in <minutes>", "Minutes until expiry (1\u201310080, i.e. up to 7 days)").option("--no-clipboard", "Don't copy URL to clipboard").option("-q, --quiet", "Print only the URL").action(async function(dir, opts) {
+    const projectDir = resolve2(dir);
+    const log = opts.quiet ? () => {
+    } : (m) => process.stderr.write(`${m}
+`);
+    const apiUrl = this.parent?.opts()?.apiUrl;
+    const client = new HTMLShipClient({ baseUrl: apiUrl });
+    const expiresIn = opts.expiresIn ? Number.parseInt(opts.expiresIn, 10) : null;
+    const useSite = opts.singleFile ? false : opts.site || isNextProject(projectDir);
+    let page;
+    if (useSite) {
+      const { files, entry } = buildAndPackageSite(projectDir, {
+        buildCmd: opts.buildCmd,
+        out: opts.out,
+        entry: opts.entry,
+        install: opts.install,
+        log
+      });
+      if (opts.dryRun) {
+        log("dry-run:   built and packaged OK; not published");
+        return;
+      }
+      try {
+        page = await client.deploySite(files, {
+          entry,
+          title: opts.title ?? null,
+          password: opts.password ?? null,
+          expiresIn
+        });
+      } catch (err) {
+        throw new HTMLShipError(`deploy failed: ${err.message}`);
+      }
+    } else {
+      const { html, bytes } = buildAndInline(projectDir, {
+        buildCmd: opts.buildCmd,
+        out: opts.out,
+        entry: opts.entry,
+        install: opts.install,
+        log
+      });
+      if (bytes > MAX_INLINE_BYTES) {
+        throw new HTMLShipError(
+          `inlined page is ${formatBytes(bytes)}, exceeds the ${formatBytes(MAX_INLINE_BYTES)} limit \u2014 try --site for multi-file hosting`
+        );
+      }
+      if (opts.dryRun) {
+        log("dry-run:   built and inlined OK; not published");
+        return;
+      }
+      try {
+        page = await client.publish(html, {
+          title: opts.title ?? null,
+          password: opts.password ?? null,
+          expiresIn,
+          sandboxMode: "relaxed"
+        });
+      } catch (err) {
+        throw new HTMLShipError(`deploy failed: ${err.message}`);
+      }
+    }
+    const keys = createKeyStore();
+    keys.remember(page.slug, {
+      owner_key: page.owner_key,
+      url: page.url,
+      title: opts.title ?? null
+    });
+    if (opts.quiet) {
+      process.stdout.write(`${page.url}
+`);
+      return;
+    }
+    process.stdout.write(`${page.url}
+`);
+    process.stderr.write(`slug:      ${page.slug}
+`);
+    process.stderr.write(`owner_key: ${page.owner_key}  (saved to ${keys.file})
+`);
+    process.stderr.write(
+      `sandbox:   relaxed${useSite ? " \xB7 multi-file site" : ""} (scripts run in an isolated origin)
+`
+    );
+    if (page.expires_at) {
+      process.stderr.write(`expires:   ${page.expires_at}
+`);
+    }
+    if (opts.clipboard !== false) {
+      const copied = await tryClipboardCopy(page.url);
+      if (copied) process.stderr.write("(URL copied to clipboard)\n");
+    }
+  });
+}
+
 // src/commands/get.ts
 init_client();
 init_errors();
@@ -498,45 +1135,6 @@ function registerListMine(program) {
 // src/commands/publish.ts
 init_client();
 init_errors();
-
-// src/io.ts
-import { readFileSync as readFileSync2 } from "fs";
-function readHtmlFromSource(source, fileFlag) {
-  if (fileFlag) {
-    return readFileSync2(fileFlag, "utf8");
-  }
-  if (source === "-" || source === void 0) {
-    if (source === void 0 && process.stdin.isTTY) {
-      throw new CliUsageError("Provide a file path or pipe HTML on stdin.");
-    }
-    return readStdinSync();
-  }
-  return readFileSync2(source, "utf8");
-}
-var CliUsageError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "CliUsageError";
-  }
-};
-function readStdinSync() {
-  try {
-    return readFileSync2(0, "utf8");
-  } catch (err) {
-    throw new CliUsageError(`failed to read stdin: ${err.message}`);
-  }
-}
-async function tryClipboardCopy(text) {
-  try {
-    const mod = await import("clipboardy");
-    await mod.default.write(text);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// src/commands/publish.ts
 function registerPublish(program) {
   program.command("publish").description("Publish an HTML document and get a URL.").argument("[source]", "file path, '-' for stdin (default: stdin if piped)").option("-f, --file <path>", "HTML file path").option("--title <title>", "Optional title").option("--password <password>", "Password-protect the page").option("--expires-in <minutes>", "Minutes until expiry (1\u201310080, i.e. up to 7 days)").option("--no-clipboard", "Don't copy URL to clipboard").option("-q, --quiet", "Print only the URL").action(async function(source, opts) {
     const html = readHtmlFromSource(source, opts.file);
@@ -573,7 +1171,7 @@ function registerPublish(program) {
       process.stderr.write(`expires:   ${page.expires_at}
 `);
     }
-    if (opts.noClipboard !== true) {
+    if (opts.clipboard !== false) {
       const copied = await tryClipboardCopy(page.url);
       if (copied) process.stderr.write("(URL copied to clipboard)\n");
     }
@@ -618,6 +1216,7 @@ function buildProgram() {
     "API base URL (default: https://api.htmlship.com or $HTMLSHIP_API_URL)"
   );
   registerPublish(program);
+  registerDeploy(program);
   registerGet(program);
   registerUpdate(program);
   registerDelete(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlship",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Host and share HTML pages from LLMs and coding agents in one line. CLI + MCP server.",
   "keywords": [
     "html",