tinyapps 0.1.0__py3-none-any.whl

tinyapps/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: tinyapps
+description: Create, update and delete single-file HTML apps (with a SQLite database) and static artifacts served by tinyapps.
+---
+# tinyapps
+
+Base URL: `<TINYAPPS_BASE_URL>`. If this is a placeholder, ask the user for the URL they open tinyapps at and replace it in this file.
+
+- App (saves data): `~/tinyapps/web/apps/<name>.html` → `<base>/apps/<name>`
+- Artifact (static): `~/tinyapps/web/artifacts/<name>.html` → `<base>/artifacts/<name>`
+- Database: `~/tinyapps/data/<name>.sqlite`, apps only, never served. Write it directly with Python `sqlite3`.
+- Names match `^[a-z0-9][a-z0-9-]{0,62}$`. Writing a file publishes it.
+
+## Sandbox
+Pages are one self-contained HTML file (inline or CDN CSS/JS). No storage, cookies, dialogs or popups.
+Apps can't make network requests; artifacts can't reach `/api`.
+
+## Data
+`await app.sql(sql, params)` runs one statement and returns rows. Use `?` params.
+The app and you may write at the same time; keep transactions short.
+
+## Delete (only when asked; permanent)
+`rm ~/tinyapps/web/apps/<name>.html ~/tinyapps/data/<name>.sqlite*` or `rm ~/tinyapps/web/artifacts/<name>.html`
+
+## Check
+`curl -so /dev/null -w '%{http_code}' http://127.0.0.1:8080/<apps|artifacts>/<name>` → 200. Service: `systemctl --user status tinyapps`.

tinyapps/server.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""tinyapps: serve AI-written HTML artifacts and apps; each app gets its own SQLite database.
+
+Usage:
+  tinyapps                         serve on TINYAPPS_PORT (default 8080)
+  tinyapps delete apps <name>      delete an app page and its database
+  tinyapps delete artifacts <name>
+  tinyapps skill                   print the agent skill (SKILL.md)
+"""
+
+import json
+import os
+import re
+import sqlite3
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from pathlib import Path
+from urllib.parse import urlsplit
+
+HOME = Path(os.environ.get("TINYAPPS_HOME", Path.home() / "tinyapps"))
+PORT = int(os.environ.get("TINYAPPS_PORT", "8080"))
+NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,62}")
+KINDS = ("apps", "artifacts")
+MAX_BODY = 1_000_000
+
+FRAME_CSP = "sandbox allow-scripts allow-downloads; connect-src 'none'; form-action 'none'"
+ARTIFACT_CSP = "sandbox allow-scripts allow-downloads; form-action 'none'"
+
+SDK = """<script>
+window.app = (() => {
+  let next = 0;
+  const pending = new Map();
+  addEventListener("message", (e) => {
+    if (e.source !== parent || !e.data || e.data.type !== "tinyapps:result") return;
+    const p = pending.get(e.data.id);
+    if (!p) return;
+    pending.delete(e.data.id);
+    if (e.data.error) p.reject(new Error(e.data.error));
+    else p.resolve(e.data.rows);
+  });
+  return {
+    name: %(name)s,
+    sql(sql, params = []) {
+      return new Promise((resolve, reject) => {
+        const id = ++next;
+        pending.set(id, { resolve, reject });
+        parent.postMessage({ type: "tinyapps:sql", id, sql, params }, "*");
+      });
+    },
+  };
+})();
+</script>
+"""
+
+HOST_PAGE = """<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>%(title)s</title>
+<style>html, body, iframe { margin: 0; border: 0; width: 100%%; height: 100%%; display: block; }</style>
+<iframe sandbox="allow-scripts allow-downloads" src="/apps/%(title)s/frame"></iframe>
+<script>
+const frame = document.querySelector("iframe");
+addEventListener("message", async (e) => {
+  if (e.source !== frame.contentWindow || !e.data || e.data.type !== "tinyapps:sql") return;
+  const { id, sql, params } = e.data;
+  let reply;
+  try {
+    const res = await fetch(%(api)s, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sql, params }),
+    });
+    const body = await res.json();
+    reply = res.ok ? { id, rows: body.rows } : { id, error: body.error || res.statusText };
+  } catch (err) {
+    reply = { id, error: String(err) };
+  }
+  frame.contentWindow.postMessage({ type: "tinyapps:result", ...reply }, "*");
+});
+</script>
+"""
+
+
+def page_path(kind, name):
+    return HOME / "web" / kind / f"{name}.html"
+
+
+def db_path(name):
+    return HOME / "data" / f"{name}.sqlite"
+
+
+def page_exists(kind, name):
+    return kind in KINDS and bool(NAME.fullmatch(name)) and page_path(kind, name).is_file()
+
+
+def _deny_attach(action, *_):
+    if action in (sqlite3.SQLITE_ATTACH, sqlite3.SQLITE_DETACH):
+        return sqlite3.SQLITE_DENY
+    return sqlite3.SQLITE_OK
+
+
+def run_sql(name, sql, params):
+    """Run one statement against the app's database and return its rows."""
+    db_path(name).parent.mkdir(parents=True, exist_ok=True)
+    con = sqlite3.connect(db_path(name), timeout=5)
+    try:
+        con.execute("PRAGMA journal_mode=WAL")
+        con.set_authorizer(_deny_attach)
+        con.row_factory = sqlite3.Row
+        with con:
+            return [dict(row) for row in con.execute(sql, params).fetchall()]
+    finally:
+        con.close()
+
+
+def inject(page, script):
+    """Insert script at the start of <head>, else after the doctype, else at the top."""
+    for pattern in (r"<head\b[^>]*>", r"<!doctype[^>]*>"):
+        m = re.search(pattern, page, re.I)
+        if m:
+            return page[: m.end()] + script + page[m.end() :]
+    return script + page
+
+
+def listing(kind):
+    names = sorted(p.stem for p in (HOME / "web" / kind).glob("*.html") if NAME.fullmatch(p.stem))
+    items = "".join(f'<li><a href="/{kind}/{n}">{n}</a></li>' for n in names) or "<li>none yet</li>"
+    return f'<!doctype html><meta charset="utf-8"><title>{kind}</title><h1>{kind}</h1><ul>{items}</ul>'
+
+
+def delete(kind, name):
+    if kind not in KINDS or not NAME.fullmatch(name):
+        sys.exit(f"invalid kind or name: {kind} {name}")
+    page = page_path(kind, name)
+    if not page.is_file():
+        sys.exit(f"no such {kind[:-1]}: {name}")
+    page.unlink()
+    if kind == "apps":
+        for suffix in ("", "-wal", "-shm"):
+            Path(f"{db_path(name)}{suffix}").unlink(missing_ok=True)
+    print(f"deleted {kind[:-1]} {name}")
+
+
+class Handler(BaseHTTPRequestHandler):
+    def send(self, status, body, ctype="text/html; charset=utf-8", csp=None):
+        data = body.encode() if isinstance(body, str) else body
+        self.send_response(status)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        if csp:
+            self.send_header("Content-Security-Policy", csp)
+        self.end_headers()
+        self.wfile.write(data)
+
+    def send_json(self, status, obj):
+        self.send(status, json.dumps(obj), "application/json")
+
+    def parts(self):
+        return urlsplit(self.path).path.strip("/").split("/")
+
+    def do_GET(self):
+        match self.parts():
+            case [""]:
+                self.send(200, '<!doctype html><meta charset="utf-8"><title>tinyapps</title>'
+                          '<ul><li><a href="/apps">apps</a></li><li><a href="/artifacts">artifacts</a></li></ul>')
+            case [kind] if kind in KINDS:
+                self.send(200, listing(kind))
+            case ["artifacts", name] if page_exists("artifacts", name):
+                self.send(200, page_path("artifacts", name).read_bytes(), csp=ARTIFACT_CSP)
+            case ["apps", name] if page_exists("apps", name):
+                self.send(200, HOST_PAGE % {"title": name, "api": json.dumps(f"/api/apps/{name}/sql")})
+            case ["apps", name, "frame"] if page_exists("apps", name):
+                page = page_path("apps", name).read_text(encoding="utf-8")
+                self.send(200, inject(page, SDK % {"name": json.dumps(name)}), csp=FRAME_CSP)
+            case _:
+                self.send_json(404, {"error": "not found"})
+
+    def do_POST(self):
+        match self.parts():
+            case ["api", "apps", name, "sql"] if page_exists("apps", name):
+                self.handle_sql(name)
+            case _:
+                self.send_json(404, {"error": "not found"})
+
+    def handle_sql(self, name):
+        # Only the host page may call the API; sandboxed pages send Origin "null". Compare
+        # hosts, not schemes, so it keeps working behind a TLS-terminating proxy.
+        if urlsplit(self.headers.get("Origin", "")).netloc != self.headers.get("Host"):
+            return self.send_json(403, {"error": "forbidden origin"})
+        if not self.headers.get("Content-Type", "").startswith("application/json"):
+            return self.send_json(415, {"error": "expected application/json"})
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+            if not 0 <= length <= MAX_BODY:
+                return self.send_json(413, {"error": "request too large"})
+            body = json.loads(self.rfile.read(length))
+            sql, params = body["sql"], body.get("params", [])
+            if not isinstance(sql, str) or not isinstance(params, (list, dict)):
+                raise ValueError("sql must be a string and params a list or object")
+        except (ValueError, KeyError, TypeError) as exc:
+            return self.send_json(400, {"error": f"bad request: {exc}"})
+        try:
+            self.send_json(200, {"rows": run_sql(name, sql, params)})
+        except sqlite3.Error as exc:
+            self.send_json(400, {"error": str(exc)})
+        except Exception as exc:
+            self.log_error("sql failed for %s: %r", name, exc)
+            self.send_json(500, {"error": str(exc)})
+
+
+def main():
+    if sys.argv[1:2] == ["delete"] and len(sys.argv) == 4:
+        return delete(sys.argv[2], sys.argv[3])
+    if sys.argv[1:] == ["skill"]:
+        return print(resources.files("tinyapps").joinpath("SKILL.md").read_text(), end="")
+    if len(sys.argv) > 1:
+        sys.exit(__doc__)
+    for kind in KINDS:
+        (HOME / "web" / kind).mkdir(parents=True, exist_ok=True)
+    (HOME / "data").mkdir(parents=True, exist_ok=True)
+    print(f"tinyapps serving {HOME} on :{PORT}", flush=True)
+    ThreadingHTTPServer(("0.0.0.0", PORT), Handler).serve_forever()
+
+
+if __name__ == "__main__":
+    main()

tinyapps-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: tinyapps
+Version: 0.1.0
+Summary: An extremely minimal, self-hosted, stateful app builder your agents can use.
+Author-email: Arjun Mahishi <arjun.mahishi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arjunmahishi/tinyapps
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tinyapps
+
+An extremely minimal, self-hosted, stateful app builder your agents can use.
+
+Ask your agent for a tool. It writes one HTML file, and if the app needs to
+remember things, a SQLite database next to it. The page is live at a URL on
+your own machine as soon as the file exists. No framework, no build step, no
+deploy: one Python file (standard library only) and a skill that teaches your
+agent the rules.
+
+- **Apps** at `/apps/<name>`: an HTML page with its own SQLite database.
+- **Artifacts** at `/artifacts/<name>`: a static page (report, chart, mockup).
+
+## Alternatives
+
+There are plenty, and most do far more. Pick tinyapps only if you want it
+small, on your own hardware, and driven by your own agent.
+
+- **[Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) / [ChatGPT Canvas](https://openai.com/index/introducing-canvas/)**: pages and small apps the assistant builds inside a chat. Hosted by the vendor and tied to their chat product.
+- **[Lovable](https://lovable.dev), [Bolt.new](https://bolt.new), [v0](https://v0.app), [Replit Agent](https://replit.com/products/agent)**: describe an app and get a complete full-stack project, built and hosted on their cloud.
+- **[Val Town](https://www.val.town)**: a hosted platform that instantly deploys small TypeScript apps and APIs, with built-in SQLite. Made for people and their agents.
+- **[PocketBase](https://pocketbase.io)**: an open-source backend in one file (database, auth, file storage, admin UI) that you self-host. You or your agent still build and serve the frontend.
+
+## How it works
+
+![How tinyapps works](https://raw.githubusercontent.com/arjunmahishi/tinyapps/main/docs/how-it-works.png)
+
+- Your agent writes `~/tinyapps/web/apps/<name>.html` and creates the
+  database `~/tinyapps/data/<name>.sqlite` directly with `sqlite3`.
+- The browser loads a host page that runs your HTML in a sandboxed iframe. App
+  code can't make network requests; its only way out is
+  `await app.sql(sql, params)`, which the host relays to the server.
+- The server picks the database from the app name in the URL, never from the
+  request. Databases are never served over HTTP.
+- Code and content are separate: this repo is the server; your pages and data
+  live in `~/tinyapps/` and never end up in git.
+
+## Run it
+
+Requires Python 3.10+.
+
+```bash
+pipx install tinyapps
+tinyapps        # serves ~/tinyapps on :8080
+```
+
+Then give your agent the skill, printed by `tinyapps skill`. For Hermes:
+
+```bash
+f=~/.hermes/skills/productivity/tinyapps/SKILL.md
+mkdir -p "${f%/*}" && [ -e "$f" ] || tinyapps skill > "$f"
+```
+
+The agent asks for your base URL on first use. It refines its copy of the
+skill over time, so the command above never overwrites it. After
+`pipx upgrade tinyapps`, compare it with `tinyapps skill` and merge any
+changes by hand.
+The skill is plain Markdown, so any agent that can write files can use it.
+
+> **tinyapps has no login.** Anyone who can reach it can open every page and
+> read or change every app's data. Keep it on a trusted network or behind an
+> authenticating proxy.
+
+## How I use it
+
+This is my setup, not a requirement. Any agent, machine or proxy works.
+
+![My setup](https://raw.githubusercontent.com/arjunmahishi/tinyapps/main/docs/my-setup.png)
+
+- **Machine**: a 10-year-old Dell Inspiron 3541 laptop (AMD A6-6310, 4 GB
+  RAM, spinning 500 GB disk) running Debian 13.
+- **Agent**: [Hermes Agent](https://github.com/NousResearch/hermes-agent). I
+  ask it for apps from chat; it writes them and replies with the link.
+- **Service**: a systemd user unit tied to Hermes, so it
+  starts and stops with the agent.
+- **Remote access**: a Cloudflare Tunnel publishes it on a subdomain, with
+  Cloudflare Access (Google login, my email only) in front. At home I also
+  reach it directly over the LAN.

tinyapps-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tinyapps/SKILL.md,sha256=7VB6HmfRdh1KA71IIElrOrqo4G5yBv3YmqRozvMno04,1291
+tinyapps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tinyapps/server.py,sha256=A2kwdnd3iLKiT8XCx8LICHlPWRrghq9SmbBUcDmvDdY,8820
+tinyapps-0.1.0.dist-info/licenses/LICENSE,sha256=YU8uus4cKNYR3S3S6jlflmcs-iNgiANUjNhYFKghdNA,1070
+tinyapps-0.1.0.dist-info/METADATA,sha256=4IcN-nh5xElNBIWxqItgbqpPkjBBAcNw3az2kbz8lQM,4236
+tinyapps-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tinyapps-0.1.0.dist-info/entry_points.txt,sha256=gmeUwcPtci1stcZWaZFuM-2UHaXqLdFZNstWZv8Jo88,50
+tinyapps-0.1.0.dist-info/top_level.txt,sha256=V4Uo-2AHsY_DHImB4Ws5gocu5muESHdeYeR8Pc-Sgbc,9
+tinyapps-0.1.0.dist-info/RECORD,,

tinyapps-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tinyapps-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tinyapps = tinyapps.server:main

tinyapps-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arjun Mahishi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tinyapps-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tinyapps