kennel 0.1.9 → 0.2.0

package/dist/site/viewer.d.ts

@@ -1,9 +1,36 @@
 export type ViewerOptions = {
+    dryRun: boolean;
     host: string;
+    hot: boolean;
     lan: boolean;
+    open: boolean;
+    /**
+     * Optional path (including query) to open in the browser, for hot-viewer flows.
+     * Example: `/folder/<encoded-folder>/views/mail`.
+     */
+    openPath?: string;
     root: string;
     port: string;
+    /**
+     * Single file to pop up, always inside `root`. Absent in folder mode.
+     */
+    target?: string;
     tailscale: boolean;
+    /**
+     * Ask the pop-up to watch the file and refresh on changes.
+     */
+    watch: boolean;
 };
+export declare function viewerFolder(root: string, value?: string | null): string;
+/**
+ * Resolve a client-supplied folder against the configured viewer root with a
+ * realpath check: the resolved candidate must be the root itself or a
+ * descendant of the root's real path. Symlink escapes, `..` traversal, and
+ * arbitrary absolute path overrides are rejected. Throws when out of scope.
+ * Used by the API routes; `viewerFolder` (multi-folder local reuse) stays
+ * permissive.
+ */
+export declare function scopedFolder(root: string, value?: string | null): string;
 export declare function splitViewerArgs(input: string[]): ViewerOptions;
+export declare function popUrl(host: string, port: string, options: ViewerOptions): string;
 export declare function viewer(input: string[]): Promise<void>;

package/dist/site/viewer.js

@@ -1,192 +1,339 @@
-import { createServer } from 'node:http';
-import { execFile, execFileSync } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { dirname, extname, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { readFolder } from '@raggle-ai/barkdown/node';
-const mime = {
-    '.css': 'text/css; charset=utf-8',
-    '.html': 'text/html; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.svg': 'image/svg+xml',
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-};
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { createServer } from "node:net";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { previewKind } from "./kinds.js";
+export function viewerFolder(root, value) {
+    return resolve(value ?? root);
+}
+/**
+ * Resolve a client-supplied folder against the configured viewer root with a
+ * realpath check: the resolved candidate must be the root itself or a
+ * descendant of the root's real path. Symlink escapes, `..` traversal, and
+ * arbitrary absolute path overrides are rejected. Throws when out of scope.
+ * Used by the API routes; `viewerFolder` (multi-folder local reuse) stays
+ * permissive.
+ */
+export function scopedFolder(root, value) {
+    const base = resolve(root);
+    const baseReal = realpathSync(base);
+    const candidate = value === undefined || value === null || value === ""
+        ? base
+        : resolve(value);
+    if (candidate === base)
+        return base;
+    const candidateReal = realpathSync(candidate);
+    const rel = relative(baseReal, candidateReal);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return candidate;
+    throw new Error("Path is outside the configured viewer root");
+}
+const loopbackHosts = new Set([
+    "127.0.0.1",
+    "::1",
+    "::ffff:127.0.0.1",
+    "localhost",
+]);
+function isLoopbackHost(host) {
+    return loopbackHosts.has(host) || host.startsWith("127.");
+}
+function encodeBase64Url(value) {
+    return Buffer.from(value, "utf8")
+        .toString("base64")
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
 export function splitViewerArgs(input) {
     let hasHost = false;
     let hasRoot = false;
     const options = {
-        host: '127.0.0.1',
+        dryRun: false,
+        host: "127.0.0.1",
+        hot: process.env.KENNEL_VIEWER_HOT === "1",
         lan: false,
+        open: false,
         root: process.cwd(),
-        port: '5173',
+        port: "5180",
         tailscale: false,
+        target: undefined,
+        watch: false,
     };
     for (let index = 0; index < input.length; index += 1) {
         const arg = input[index];
-        if (arg === '--port') {
-            options.port = input[index + 1] ?? '';
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--hot") {
+            options.hot = true;
+            continue;
+        }
+        if (arg === "--open") {
+            options.open = true;
+            continue;
+        }
+        if (arg === "--no-open") {
+            options.open = false;
+            continue;
+        }
+        if (arg === "--watch") {
+            options.watch = true;
+            continue;
+        }
+        if (arg === "--static") {
+            options.hot = false;
+            continue;
+        }
+        if (arg === "--port") {
+            options.port = input[index + 1] ?? "";
             index += 1;
             continue;
         }
-        if (arg.startsWith('--port=')) {
-            options.port = arg.slice('--port='.length);
+        if (arg.startsWith("--port=")) {
+            options.port = arg.slice("--port=".length);
             continue;
         }
-        if (arg === '--host') {
-            options.host = input[index + 1] ?? '';
+        if (arg === "--host") {
+            options.host = input[index + 1] ?? "";
             hasHost = true;
             index += 1;
             continue;
         }
-        if (arg.startsWith('--host=')) {
-            options.host = arg.slice('--host='.length);
+        if (arg.startsWith("--host=")) {
+            options.host = arg.slice("--host=".length);
             hasHost = true;
             continue;
         }
-        if (arg === '--lan') {
+        if (arg === "--lan") {
             options.lan = true;
             continue;
         }
-        if (arg === '--tailscale') {
+        if (arg === "--tailscale") {
             options.tailscale = true;
             continue;
         }
-        if (arg.startsWith('-'))
+        if (arg.startsWith("-"))
             throw new Error(`Unknown viewer option: ${arg}`);
+        const candidate = resolve(arg);
+        const isDirectory = existsSync(candidate) && statSync(candidate).isDirectory();
+        if (isDirectory) {
+            if (hasRoot)
+                throw new Error("kennel accepts one folder");
+            options.root = candidate;
+            hasRoot = true;
+            continue;
+        }
         if (hasRoot)
-            throw new Error('kennel accepts one folder');
-        options.root = resolve(arg);
+            throw new Error("kennel accepts one folder");
+        options.root = dirname(candidate);
+        options.target = candidate;
         hasRoot = true;
     }
+    // Opt out of opening the default browser even when a command implies it
+    // (`--no-open` wins over earlier flags; the env var always disables).
+    if (process.env.KENNEL_OPEN === "0")
+        options.open = false;
     if (!options.port || !/^\d+$/.test(options.port)) {
-        throw new Error('kennel requires a numeric port');
+        throw new Error("kennel requires a numeric port");
     }
     if (!options.host)
-        throw new Error('kennel requires a host');
+        throw new Error("kennel requires a host");
     if ((options.lan || options.tailscale) && hasHost) {
-        throw new Error('kennel does not accept --host with --lan or --tailscale');
+        throw new Error("kennel does not accept --host with --lan or --tailscale");
     }
     if (options.lan && options.tailscale) {
-        throw new Error('kennel accepts one remote access mode');
+        throw new Error("kennel accepts one remote access mode");
     }
     if (options.lan)
-        options.host = lanHost();
+        options.host = "0.0.0.0";
     if (!existsSync(options.root) || !statSync(options.root).isDirectory()) {
         throw new Error(`Folder not found: ${options.root}`);
     }
+    if (options.target) {
+        const targetDetails = statSync(options.target);
+        if (!targetDetails.isFile()) {
+            throw new Error(`File not found: ${options.target}`);
+        }
+        if (!previewKind(options.target)) {
+            throw new Error(`Kennel cannot preview this file type: ${options.target}`);
+        }
+    }
     return options;
 }
+export function popUrl(host, port, options) {
+    const scheme = options.tailscale ? "https" : "http";
+    const authority = options.tailscale ? host : `${host}:${port}`;
+    const url = new URL(`${scheme}://${authority}/`);
+    if (!options.target) {
+        url.pathname = `/folder/${encodeBase64Url(options.root)}/notes`;
+        return url.href;
+    }
+    url.pathname = `/folder/${encodeBase64Url(options.root)}/document/${encodeBase64Url(relative(options.root, options.target))}`;
+    if (options.watch)
+        url.searchParams.set("watch", "1");
+    return url.href;
+}
+function viewerPortWasExplicit(input) {
+    return input.some((arg) => arg === "--port" || arg.startsWith("--port="));
+}
+function isSameOrDescendant(parent, child) {
+    const parentReal = realpathSync(parent);
+    const childReal = realpathSync(child);
+    const childRelative = relative(parentReal, childReal);
+    return childRelative === "" || (!childRelative.startsWith("..") && !isAbsolute(childRelative));
+}
+async function runningViewer(url) {
+    try {
+        const response = await fetch(`${url}/api/health`, {
+            signal: AbortSignal.timeout(1_000),
+        });
+        if (!response.ok)
+            return undefined;
+        const body = await response.json();
+        if (body &&
+            typeof body === "object" &&
+            typeof body.root === "string" &&
+            typeof body.viewer === "string" &&
+            (body.viewer === "kennel-core" || body.viewer === "kennel-vite")) {
+            return { root: body.root, viewer: body.viewer };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function canListen(port, host) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.listen(port, host, () => server.close(() => resolve(true)));
+    });
+}
+async function availableViewerPort(start, host) {
+    for (let port = start; port <= 65535; port += 1) {
+        if (await canListen(port, host))
+            return port;
+    }
+    throw new Error(`Kennel could not find a free port at or above ${start}`);
+}
+function openUrl(url) {
+    const command = process.platform === "darwin"
+        ? "/usr/bin/open"
+        : process.platform === "win32"
+            ? "explorer.exe"
+            : "xdg-open";
+    execFile(command, [url], (error) => {
+        if (error)
+            console.error(`Could not open browser: ${error.message}`);
+    });
+}
 function lanHost() {
-    const route = execFileSync('/sbin/route', ['-n', 'get', 'default'], { encoding: 'utf8' });
+    const route = execFileSync("/sbin/route", ["-n", "get", "default"], {
+        encoding: "utf8",
+    });
     const device = route.match(/interface:\s+(\S+)/)?.[1];
     if (!device)
-        throw new Error('kennel could not find the local network interface');
-    const host = execFileSync('/usr/sbin/ipconfig', ['getifaddr', device], {
-        encoding: 'utf8',
+        throw new Error("kennel could not find the local network interface");
+    const host = execFileSync("/usr/sbin/ipconfig", ["getifaddr", device], {
+        encoding: "utf8",
     }).trim();
     if (!host)
         throw new Error(`kennel could not find an address for ${device}`);
     return host;
 }
 function tailscaleHost() {
-    const status = JSON.parse(execFileSync('tailscale', ['status', '--json'], { encoding: 'utf8' }));
-    const host = typeof status.Self?.DNSName === 'string' ? status.Self.DNSName.replace(/\.$/, '') : '';
+    const status = JSON.parse(execFileSync("tailscale", ["status", "--json"], { encoding: "utf8" }));
+    const host = typeof status.Self?.DNSName === "string"
+        ? status.Self.DNSName.replace(/\.$/, "")
+        : "";
     if (host)
         return host;
-    throw new Error('kennel could not find the Tailscale DNS name');
+    throw new Error("kennel could not find the Tailscale DNS name");
 }
 export async function viewer(input) {
+    const portExplicit = viewerPortWasExplicit(input);
     const options = splitViewerArgs(input);
-    const web = resolve(dirname(fileURLToPath(import.meta.url)), '../../web');
-    if (!existsSync(resolve(web, 'index.html'))) {
+    if (options.hot) {
+        const { hotViewer } = await import("./hot-viewer.js");
+        await hotViewer(options);
+        return;
+    }
+    const web = resolve(dirname(fileURLToPath(import.meta.url)), "../../web");
+    if (!existsSync(resolve(web, "index.html"))) {
         throw new Error(`Kennel web app not found. Run the CLI build first.`);
     }
-    const server = createServer(async (request, response) => {
-        try {
-            const url = new URL(request.url ?? '/', 'http://127.0.0.1');
-            if (url.pathname === '/api/health') {
-                response.writeHead(200, {
-                    'Cache-Control': 'no-store',
-                    'Content-Type': 'application/json; charset=utf-8',
-                });
-                response.end(JSON.stringify({ root: options.root }));
-                return;
-            }
-            if (url.pathname === '/api/documents') {
-                const root = resolve(url.searchParams.get('path') ?? options.root);
-                const body = JSON.stringify(await readFolder(root));
-                response.writeHead(200, {
-                    'Cache-Control': 'no-store',
-                    'Content-Type': 'application/json; charset=utf-8',
-                });
-                response.end(body);
-                return;
-            }
-            if (url.pathname === '/api/open-folder' && request.method === 'POST') {
-                const root = resolve(url.searchParams.get('path') ?? options.root);
-                if (!existsSync(root) || !statSync(root).isDirectory()) {
-                    response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-                    response.end(`Folder not found: ${root}`);
-                    return;
-                }
-                execFile('/usr/bin/open', [root], (error) => {
-                    if (error) {
-                        response.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
-                        response.end('Could not open folder');
-                        return;
-                    }
-                    response.writeHead(204);
-                    response.end();
-                });
-                return;
-            }
-            const requested = url.pathname === '/' ? 'index.html' : decodeURIComponent(url.pathname.slice(1));
-            const path = resolve(web, requested);
-            const escaped = relative(web, path).startsWith('..');
-            if (escaped) {
-                response.writeHead(404);
-                response.end('Not found');
-                return;
-            }
-            const appRoute = !extname(path);
-            const file = appRoute ? resolve(web, 'index.html') : path;
-            const body = await readFile(file);
-            response.writeHead(200, {
-                'Cache-Control': appRoute || file.endsWith('index.html') ? 'no-store' : 'public, max-age=3600',
-                'Content-Type': mime[extname(file)] ?? 'application/octet-stream',
-            });
-            response.end(body);
-        }
-        catch (error) {
-            if (response.headersSent) {
-                response.destroy(error instanceof Error ? error : undefined);
-                return;
-            }
-            response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-            response.end(error instanceof Error ? error.message : 'Not found');
-        }
-    });
-    await new Promise((done, fail) => {
-        server.once('error', fail);
-        server.listen(Number(options.port), options.host, done);
+    // The server only acts on the machine when it is reachable on loopback.
+    // Explicit --lan/--tailscale/--host bindings disable host actions (opening
+    // folders/files in apps on the server) and gate the capabilities reported
+    // to the client, so a remote phone can never trigger an app on the server.
+    const remote = options.tailscale || !isLoopbackHost(options.host);
+    // Single-file pop mode serves exactly the popped file, never siblings.
+    const lockedTarget = options.target
+        ? realpathSync(options.target)
+        : undefined;
+    const { createKennelApi } = await import("../core/runtime.js");
+    const displayHost = options.tailscale
+        ? tailscaleHost()
+        : options.lan
+            ? lanHost()
+            : options.host;
+    if (remote)
+        process.env.KENNEL_VIEWER_HOSTS = [
+            process.env.KENNEL_VIEWER_HOSTS,
+            displayHost,
+        ]
+            .filter(Boolean)
+            .join(",");
+    const initialViewerUrl = `http://${options.host}:${options.port}`;
+    const existing = await runningViewer(initialViewerUrl);
+    if (existing && isSameOrDescendant(existing.root, options.root)) {
+        const viewerUrl = popUrl(displayHost, options.port, options);
+        console.log(viewerUrl);
+        console.log(`Kennel is already running at ${viewerUrl}`);
+        if (options.open)
+            openUrl(viewerUrl);
+        return;
+    }
+    if (!portExplicit) {
+        options.port = String(await availableViewerPort(Number(options.port), options.host));
+    }
+    const api = createKennelApi({
+        root: options.root,
+        host: options.host,
+        remoteAccess: remote,
+        restrictToRoot: true,
+        lockedFile: lockedTarget,
+        webRoot: web,
     });
-    console.log(`Reading documents from ${options.root}`);
-    if (options.tailscale) {
-        execFileSync('tailscale', ['serve', '--bg', '--yes', options.port]);
-        console.log(`Kennel is running at https://${tailscaleHost()}`);
+    try {
+        await api.listen(Number(options.port));
+        console.log(`Reading documents from ${options.root}`);
+        if (options.tailscale) {
+            execFileSync("tailscale", ["serve", "--bg", "--yes", options.port]);
+        }
+        const viewerUrl = popUrl(displayHost, options.port, options);
+        console.log(viewerUrl);
+        console.log(`Kennel is running at ${viewerUrl}`);
+        console.log("Press Ctrl+C to stop.");
+        if (options.open)
+            openUrl(viewerUrl);
+        await new Promise((done) => {
+            const close = () => {
+                process.off("SIGINT", close);
+                process.off("SIGTERM", close);
+                done();
+            };
+            process.once("SIGINT", close);
+            process.once("SIGTERM", close);
+        });
     }
-    else {
-        console.log(`Kennel is running at http://${options.host}:${options.port}`);
+    finally {
+        await api.close();
     }
-    console.log('Press Ctrl+C to stop.');
-    const close = () => server.close();
-    process.once('SIGINT', close);
-    process.once('SIGTERM', close);
-    await new Promise((done) => server.once('close', done));
     if (options.tailscale) {
-        execFileSync('tailscale', ['serve', '--https=443', 'off']);
+        execFileSync("tailscale", ["serve", "--https=443", "off"]);
     }
 }

package/node_modules/@libsql/client/README.md

@@ -0,0 +1,128 @@
+<p align="center">
+  <a href="https://tur.so/turso-ts">
+    <picture>
+      <img src="/.github/cover.png" alt="libSQL TypeScript" />
+    </picture>
+  </a>
+  <h1 align="center">libSQL TypeScript</h1>
+</p>
+
+<p align="center">
+  Databases for all TypeScript and JS multi-tenant apps.
+</p>
+
+<p align="center">
+  <a href="https://tur.so/turso-ts"><strong>Turso</strong></a> ·
+  <a href="https://docs.turso.tech"><strong>Docs</strong></a> ·
+  <a href="https://docs.turso.tech/sdk/ts/quickstart"><strong>Quickstart</strong></a> ·
+  <a href="https://docs.turso.tech/sdk/ts/reference"><strong>SDK Reference</strong></a> ·
+  <a href="https://turso.tech/blog"><strong>Blog &amp; Tutorials</strong></a>
+</p>
+
+<p align="center">
+  <a href="LICENSE">
+    <picture>
+      <img src="https://img.shields.io/github/license/tursodatabase/libsql-client-ts?color=0F624B" alt="MIT License" />
+    </picture>
+  </a>
+  <a href="https://tur.so/discord-ts">
+    <picture>
+      <img src="https://img.shields.io/discord/933071162680958986?color=0F624B" alt="Discord" />
+    </picture>
+  </a>
+  <a href="#contributors">
+    <picture>
+      <img src="https://img.shields.io/github/contributors/tursodatabase/libsql-client-ts?color=0F624B" alt="Contributors" />
+    </picture>
+  </a>
+  <a href="https://www.npmjs.com/package/@libsql/client">
+    <picture>
+      <img src="https://img.shields.io/npm/dw/%40libsql%2Fclient?color=0F624B" alt="Weekly downloads" />
+    </picture>
+  </a>
+  <a href="/examples">
+    <picture>
+      <img src="https://img.shields.io/badge/browse-examples-0F624B" alt="Examples" />
+    </picture>
+  </a>
+</p>
+
+> **Looking for the Turso serverless package?** Check out [`@tursodatabase/serverless`](https://www.npmjs.com/package/@tursodatabase/serverless) — the lightest option with zero native dependencies, and will be the driver to later support concurrent writes. Use `@libsql/client` if you need a battle-tested driver today with ORM integration.
+
+## Features
+
+-   🔌 Works offline with [Embedded Replicas](https://docs.turso.tech/features/embedded-replicas/introduction)
+-   🌎 Works with remote Turso databases
+-   ✨ Works with Turso [AI & Vector Search](https://docs.turso.tech/features/ai-and-embeddings)
+-   🔐 Supports [encryption at rest](https://docs.turso.tech/libsql#encryption-at-rest)
+
+## Install
+
+```bash
+npm install @libsql/client
+```
+
+## Quickstart
+
+The example below uses Embedded Replicas and syncs every minute from Turso.
+
+```ts
+import { createClient } from "@libsql/client";
+
+export const turso = createClient({
+    url: "file:local.db",
+    syncUrl: process.env.TURSO_DATABASE_URL,
+    authToken: process.env.TURSO_AUTH_TOKEN,
+    syncInterval: 60000,
+});
+
+await turso.batch(
+    [
+        "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)",
+        {
+            sql: "INSERT INTO users(name) VALUES (?)",
+            args: ["Iku"],
+        },
+    ],
+    "write",
+);
+
+await turso.execute({
+    sql: "SELECT * FROM users WHERE id = ?",
+    args: [1],
+});
+```
+
+## Examples
+
+| Example                               | Description                                                                             |
+| ------------------------------------- | --------------------------------------------------------------------------------------- |
+| [local](examples/local)               | Uses libsql with a local SQLite file. Creates database, inserts data, and queries.      |
+| [remote](examples/remote)             | Connects to a remote database. Requires environment variables for URL and auth token.   |
+| [sync](examples/sync)                 | Demonstrates synchronization between local and remote databases.                        |
+| [batch](examples/batch)               | Executes multiple SQL statements in a single batch operation.                           |
+| [transactions](examples/transactions) | Shows transaction usage: starting, performing operations, and committing/rolling back.  |
+| [memory](examples/memory)             | Uses an in-memory SQLite database for temporary storage or fast access.                 |
+| [vector](examples/vector)             | Works with vector embeddings, storing and querying for similarity search.               |
+| [encryption](examples/encryption)     | Creates and uses an encrypted SQLite database, demonstrating setup and data operations. |
+| [ollama](examples/ollama)             | Similarity search with Ollama and Mistral.                                              |
+
+## Documentation
+
+Visit our [official documentation](https://docs.turso.tech/sdk/ts).
+
+## Support
+
+Join us [on Discord](https://tur.so/discord-ts) to get help using this SDK. Report security issues [via email](mailto:security@turso.tech).
+
+## Contributors
+
+See the [contributing guide](CONTRIBUTING.md) to learn how to get involved.
+
+![Contributors](https://contrib.nn.ci/api?repo=tursodatabase/libsql-client-ts)
+
+<a href="https://github.com/tursodatabase/libsql-client-ts/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">
+  <picture>
+    <img src="https://img.shields.io/github/issues-search/tursodatabase/libsql-client-ts?label=good%20first%20issue&query=label%3A%22good%20first%20issue%22%20&color=0F624B" alt="good first issue" />
+  </picture>
+</a>