htmlship 0.1.5 → 0.2.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,260 @@ var init_errors = __esm({
   }
 });
 
+// src/build.ts
+import { spawnSync } from "child_process";
+import { existsSync, readFileSync, statSync } from "fs";
+import { dirname, extname, isAbsolute, join, relative, resolve } 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 resolveOutputDir(dir, override) {
+  const candidates = override ? [override] : ["dist", "build"];
+  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}` : "no build output found (looked for dist/ and build/; use --out to specify)"
+  );
+}
+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 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 = join(outDir, opts.entry ?? "index.html");
+  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 LOCKFILES, DEFAULT_BUILD_TIMEOUT_MS, MIME;
+var init_build = __esm({
+  "src/build.ts"() {
+    "use strict";
+    init_errors();
+    LOCKFILES = [
+      ["pnpm-lock.yaml", "pnpm"],
+      ["yarn.lock", "yarn"],
+      ["bun.lockb", "bun"],
+      ["bun.lock", "bun"],
+      ["package-lock.json", "npm"]
+    ];
+    DEFAULT_BUILD_TIMEOUT_MS = 5 * 6e4;
+    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.2.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 +330,28 @@ 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"
+        });
+      }
       async get(slug) {
         return await this.request("GET", `/api/v1/pages/${encodeURIComponent(slug)}`);
       }
@@ -240,6 +500,52 @@ function buildMcpServer(client) {
       }
     }
   );
+  server.registerTool(
+    "deploy_project",
+    {
+      description: "Build a local frontend project (npm/pnpm/yarn/bun) and publish the compiled app as one self-contained, script-enabled page. Runs the project's build script ON THIS MACHINE, inlines the output (dist/ or build/) into a single HTML file, and publishes it with relaxed sandboxing so its JavaScript runs in an isolated origin. The owner_key returned is the only credential to update or delete this page 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/ or build/)."),
+        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, install, title, password, expires_in }) => {
+      try {
+        const page = await c.deploy(dir, {
+          buildCmd: build_cmd ?? void 0,
+          out: out ?? 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 +634,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, 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,7 +652,7 @@ 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];
@@ -420,6 +726,117 @@ 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_BYTES = 10 * 1024 * 1024;
+function registerDeploy(program) {
+  program.command("deploy").description(
+    "Build a frontend project and publish the compiled app as one self-contained page."
+  ).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/ or build/)").option("--entry <file>", "Entry HTML within the output dir (default: index.html)").option("--install", "Run dependency install before building").option("--dry-run", "Build and inline, 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 { html, bytes } = buildAndInline(projectDir, {
+      buildCmd: opts.buildCmd,
+      out: opts.out,
+      entry: opts.entry,
+      install: opts.install,
+      log
+    });
+    if (bytes > MAX_BYTES) {
+      throw new HTMLShipError(
+        `inlined page is ${formatBytes(bytes)}, exceeds the ${formatBytes(MAX_BYTES)} limit`
+      );
+    }
+    if (opts.dryRun) {
+      log("dry-run:   built and inlined OK; not published");
+      return;
+    }
+    const apiUrl = this.parent?.opts()?.apiUrl;
+    const client = new HTMLShipClient({ baseUrl: apiUrl });
+    let page;
+    try {
+      page = await client.publish(html, {
+        title: opts.title ?? null,
+        password: opts.password ?? null,
+        expiresIn: opts.expiresIn ? Number.parseInt(opts.expiresIn, 10) : null,
+        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 (scripts run in an isolated origin)\n");
+    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 +915,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 +951,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 +996,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.2.0",
   "description": "Host and share HTML pages from LLMs and coding agents in one line. CLI + MCP server.",
   "keywords": [
     "html",