ollanet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,248 @@
+# ollanet
+
+Chat with **Ollama** servers on **any network you can reach** — LAN, localhost, Tailscale, VPN, or a raw IP.
+
+Scan for models, fire prompts, and continue conversations later by a short hash. No browser UI required.
+
+## Origin
+
+This started as a selfish little script. I had Ollama running on a laptop on my Tailscale network and wanted an easy way to discover it, poke at the models, and actually talk to them from another machine — without babysitting IPs or opening a browser. One scan/prompt tool later, chats by hash showed up, LAN discovery crept in, and the thing grew into **ollanet**: a tiny CLI for using Ollama over whatever network you already have.
+
+## Related: Finetuna
+
+**ollanet** is the client-side / network tool. On the machine that *runs* Ollama, use **[Finetuna](https://github.com/Catalyst-Forge-LLC/finetuna)** to turn a stock model into a GPU-tuned, named variant (context, batch, Modelfile, auto-tune).
+
+Typical loop:
+
+1. On the host: `finetuna` → create something like `gemma4-ctx32k`
+2. From anywhere on the network: `ollanet scan` → `ollanet prompt that-host gemma4-ctx32k "…"`
+
+They share the same Ollama API; Finetuna shapes the models, ollanet finds and chats with them.
+
+## Features
+
+- **Discover** Ollama hosts from localhost, `config.hosts`, `OLLANET_HOSTS`, optional Tailscale, and optional LAN scan
+- **Prompt** any hostname/IP/model with streaming replies
+- **Persist** chats as `responses/<hash>.json` with topic, machine, model, timestamps
+- **Continue** any thread with `--chat <hash>`
+- **Configure** per-machine defaults (model, temperature, context, …)
+
+## Requirements
+
+- Node.js 20+
+- One or more [Ollama](https://ollama.com) servers reachable on port `11434` (or a custom port)
+
+Tailscale is optional. If the `tailscale` CLI is present, peers are included automatically.
+
+## Install
+
+Run without installing:
+
+```bash
+npx ollanet scan                                                  # from npm (once published)
+npx --allow-git=all github:Catalyst-Forge-LLC/ollanet scan        # straight from GitHub
+```
+
+> npm 12+ blocks git dependencies by default, hence `--allow-git=all` for the
+> GitHub form (npm ≤11 doesn't need it). Note that npx runs a one-off command —
+> it does not put `ollanet` on your PATH.
+
+Or install globally, which puts the `ollanet` command on your PATH:
+
+```bash
+npm install -g ollanet                                            # from npm (once published)
+npm install -g --allow-git=all github:Catalyst-Forge-LLC/ollanet  # from GitHub
+ollanet scan
+```
+
+When installed this way, config lives at `~/.ollanet/config.json` and chats are
+saved to `~/.ollanet/responses/`.
+
+### From a checkout (development)
+
+```bash
+cd ollanet
+pnpm install         # also builds dist/ via the prepare hook
+pnpm link --global   # optional: put `ollanet` on your PATH
+
+# Or without a global link:
+pnpm ollanet -- help
+pnpm scan
+pnpm prompt -- localhost "hello"
+pnpm chats
+```
+
+A checkout uses the repo-local `config.json` and `responses/` instead of `~/.ollanet/`.
+
+## Quick start
+
+```bash
+# Find Ollama servers (localhost + configured hosts + Tailscale if available)
+ollanet scan
+
+# Also TCP-scan your local /24s for open Ollama ports
+ollanet scan --lan
+
+# Talk to a machine by name, MagicDNS name, or IP
+ollanet prompt localhost "What is MagicDNS?"
+ollanet prompt 192.168.1.50 gemma4:12b "Hello from the LAN"
+
+# Continue later
+ollanet prompt --chat a1b2c3d4e5f6 "Give a concrete example"
+
+# Browse saved chats
+ollanet chats
+ollanet chats --id a1b2c3d4e5f6
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ollanet scan` | Probe known/discovered hosts for Ollama + list models |
+| `ollanet prompt …` | Send a prompt / continue a chat |
+| `ollanet chats` | List or inspect saved transcripts |
+
+### `scan` options
+
+- `--json` — machine-readable output
+- `--all` — also probe offline Tailscale peers
+- `--lan` — scan local LAN CIDRs for open Ollama ports
+
+### `prompt` options
+
+```text
+ollanet prompt <machine|ip> [model] <prompt...>
+ollanet prompt --chat <hash> <prompt...>
+```
+
+| Flag | Meaning |
+|---|---|
+| `--chat <hash>` | Continue a saved chat |
+| `--machine <name>` | Explicit machine (or override when continuing) |
+| `--model <name>` | Model override |
+| `--system <text>` | System prompt |
+| `--temperature <n>` | Sampling temperature |
+| `--num-predict <n>` | Max tokens to generate |
+| `--num-ctx <n>` | Context window |
+| `--keep-alive <value>` | Keep model loaded (`5m`, `0`, `-1`, …) |
+| `--format json\|<schema>` | JSON mode / schema |
+| `--no-stream` | Buffer the full reply |
+| `--no-save` | Do not write a transcript |
+| `--json` | Emit JSON (includes chat id when saved) |
+
+Machine can be a discovered name, hostname, FQDN, or IP (`192.168.1.50`, `host:11434`). Direct addresses work even if they were never scanned.
+
+### `chats` options
+
+- `--json` — list summary JSON
+- `--id <hash>` — show one chat (full JSON with `--json`)
+
+## Discovery
+
+ollanet combines several sources (deduped by `ip:port`):
+
+| Source | When |
+|---|---|
+| localhost | Always (unless disabled) |
+| `config.hosts` | Always when configured |
+| `OLLANET_HOSTS` | Env comma/space list of hosts/IPs |
+| Tailscale | If `tailscale status --json` works |
+| LAN scan | `ollanet scan --lan` or `discovery.lan: true` |
+
+## Configuration
+
+Edit `~/.ollanet/config.json` (installed) or `config.json` (checkout) — or point
+`OLLANET_CONFIG` at another file:
+
+```json
+{
+  "hosts": [
+    "192.168.1.50",
+    { "name": "studio", "host": "studio.local", "port": 11434 }
+  ],
+  "discovery": {
+    "localhost": true,
+    "tailscale": true,
+    "lan": false,
+    "cidrs": ["192.168.1.0/24"]
+  },
+  "defaultModels": {
+    "localhost": "llama3.2:1b",
+    "studio": "gemma4:12b"
+  },
+  "defaults": {
+    "temperature": 0.7,
+    "num_predict": 512,
+    "keep_alive": "5m"
+  },
+  "machineDefaults": {
+    "studio": { "num_ctx": 16384 }
+  }
+}
+```
+
+**Precedence:** CLI flags → env vars → `machineDefaults` → `defaults`.
+
+### Environment
+
+| Variable | Purpose |
+|---|---|
+| `OLLANET_CONFIG` | Path to config JSON |
+| `OLLANET_RESPONSES_DIR` | Chat transcript directory |
+| `OLLANET_HOSTS` | Extra hosts/IPs to include |
+| `OLLANET_LAN_TIMEOUT_MS` | Per-IP LAN probe timeout (default `200`) |
+| `OLLANET_LAN_CONCURRENCY` | LAN probe concurrency (default `64`) |
+| `OLLAMA_PORT` | Default Ollama port (`11434`) |
+| `OLLAMA_TEMPERATURE` | Default temperature |
+| `OLLAMA_NUM_PREDICT` | Default max tokens |
+| `OLLAMA_NUM_CTX` | Default context size |
+| `OLLAMA_KEEP_ALIVE` | Default keep-alive |
+| `OLLAMA_FORMAT` | Default format (`json` or schema JSON) |
+| `OLLAMA_SYSTEM` | Default system prompt |
+| `OLLAMA_TIMEOUT_MS` | HTTP scan/probe timeout |
+| `OLLAMA_CONCURRENCY` | Scan concurrency |
+
+## Chat transcripts
+
+Each saved chat is a JSON file:
+
+```text
+~/.ollanet/responses/<hash>.json   # installed
+responses/<hash>.json              # checkout
+```
+
+Fields include `id`, `topic`, `machine`, `model`, `system`, `created_at`, `updated_at`, and a `messages[]` array (`role`, `content`, `timestamp`, plus assistant `stats`).
+
+The first turn asks the model for a short topic title (falls back to the prompt text).
+
+## Project layout
+
+```text
+ollanet/
+  src/
+    cli.ts            # subcommand router (CLI entry)
+    hosts.ts          # discovery + host resolution
+    scan.ts
+    prompt.ts
+    chats.ts
+    chat-store.ts
+    config.ts
+    paths.ts          # checkout vs installed path resolution
+  dist/               # compiled output (published to npm)
+  config.json
+  responses/          # gitignored chat history
+```
+
+## Development
+
+```bash
+pnpm install          # builds dist/ via prepare
+pnpm typecheck
+pnpm ollanet -- scan  # runs from source via tsx
+pnpm build            # compile dist/ manually
+```
+
+## License
+
+MIT

package/dist/chat-store.js

@@ -0,0 +1,131 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { defaultResponsesDir } from "./paths.js";
+const RESPONSES_DIR = process.env.OLLANET_RESPONSES_DIR ??
+    process.env.OLLAMA_RESPONSES_DIR ??
+    defaultResponsesDir();
+export function responsesDir() {
+    return RESPONSES_DIR;
+}
+export function newChatId() {
+    return randomBytes(6).toString("hex");
+}
+export function chatPath(id) {
+    const safe = normalizeChatId(id);
+    return path.join(RESPONSES_DIR, `${safe}.json`);
+}
+export function normalizeChatId(id) {
+    const cleaned = id.trim().toLowerCase().replace(/\.json$/i, "");
+    if (!/^[a-f0-9]{8,32}$/.test(cleaned)) {
+        throw new Error(`Invalid chat id "${id}". Expected a hex hash from a prior prompt.`);
+    }
+    return cleaned;
+}
+export async function ensureResponsesDir() {
+    await mkdir(RESPONSES_DIR, { recursive: true });
+    return RESPONSES_DIR;
+}
+export async function loadChat(id) {
+    const safe = normalizeChatId(id);
+    try {
+        const raw = await readFile(chatPath(safe), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed.id || !Array.isArray(parsed.messages)) {
+            throw new Error("missing id/messages");
+        }
+        return parsed;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new Error(`Chat not found: ${safe} (${chatPath(safe)})`);
+        }
+        throw new Error(`Failed to load chat ${safe}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+export async function saveChat(chat) {
+    await ensureResponsesDir();
+    const file = chatPath(chat.id);
+    await writeFile(file, `${JSON.stringify(chat, null, 2)}\n`, "utf8");
+    return file;
+}
+export function createChat(opts) {
+    const now = new Date().toISOString();
+    return {
+        id: newChatId(),
+        topic: opts.topic?.trim() || "Untitled chat",
+        created_at: now,
+        updated_at: now,
+        machine: opts.machine,
+        model: opts.model,
+        ...(opts.system ? { system: opts.system } : {}),
+        messages: [],
+    };
+}
+export function appendMessage(chat, message) {
+    const entry = {
+        ...message,
+        timestamp: message.timestamp ?? new Date().toISOString(),
+    };
+    chat.messages.push(entry);
+    chat.updated_at = entry.timestamp;
+    if (message.machine)
+        chat.machine = message.machine;
+    if (message.model)
+        chat.model = message.model;
+    return entry;
+}
+export async function listChats() {
+    await ensureResponsesDir();
+    const files = (await readdir(RESPONSES_DIR))
+        .filter((f) => f.endsWith(".json"))
+        .sort();
+    const chats = [];
+    for (const file of files) {
+        try {
+            const raw = await readFile(path.join(RESPONSES_DIR, file), "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.id && Array.isArray(parsed.messages))
+                chats.push(parsed);
+        }
+        catch {
+            // skip corrupt files
+        }
+    }
+    chats.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+    return chats;
+}
+/** Fallback topic from the first user message when model summarization fails. */
+export function topicFromPrompt(prompt) {
+    const oneLine = prompt.replace(/\s+/g, " ").trim();
+    if (!oneLine)
+        return "Untitled chat";
+    if (oneLine.length <= 72)
+        return oneLine;
+    return `${oneLine.slice(0, 69).trimEnd()}...`;
+}
+export function cleanTopic(raw, fallback) {
+    const cleaned = raw
+        .replace(/^["'`]+|["'`]+$/g, "")
+        .replace(/^(topic|title)\s*:\s*/i, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned)
+        return fallback;
+    if (cleaned.length <= 80)
+        return cleaned;
+    return `${cleaned.slice(0, 77).trimEnd()}...`;
+}
+export function toApiMessages(chat) {
+    const out = [];
+    if (chat.system) {
+        out.push({ role: "system", content: chat.system });
+    }
+    for (const msg of chat.messages) {
+        if (msg.role === "system")
+            continue;
+        out.push({ role: msg.role, content: msg.content });
+    }
+    return out;
+}

package/dist/chats.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * List saved ollanet chats.
+ *
+ * Usage:
+ *   ollanet chats
+ *   ollanet chats --json
+ *   ollanet chats --id a1b2c3d4e5f6
+ */
+import { loadChat, listChats, responsesDir, } from "./chat-store.js";
+function usage() {
+    console.error(`Usage: ollanet chats [--json] [--id <hash>]
+
+Lists transcripts in ${responsesDir()}.
+
+Options:
+  --json       Machine-readable output
+  --id <hash>  Show one chat (messages included with --json, preview otherwise)`);
+    process.exit(1);
+}
+function parseArgs(argv) {
+    const args = [...argv];
+    let json = false;
+    let id;
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (arg === "--")
+            continue;
+        if (arg === "--help" || arg === "-h")
+            usage();
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--id" || arg.startsWith("--id=")) {
+            id = arg.includes("=") ? arg.slice("--id=".length) : args.shift();
+            if (!id) {
+                console.error("--id requires a value");
+                usage();
+            }
+            continue;
+        }
+        console.error(`Unknown flag: ${arg}`);
+        usage();
+    }
+    return { json, id };
+}
+function pad(value, width) {
+    if (value.length >= width)
+        return `${value.slice(0, width - 1)}…`;
+    return value.padEnd(width);
+}
+function formatWhen(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mi = String(d.getMinutes()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd} ${hh}:${mi}`;
+}
+function summarize(chat) {
+    return {
+        id: chat.id,
+        topic: chat.topic,
+        machine: chat.machine,
+        model: chat.model,
+        messages: chat.messages.length,
+        created_at: chat.created_at,
+        updated_at: chat.updated_at,
+        system: chat.system ?? null,
+    };
+}
+function printTable(chats) {
+    if (chats.length === 0) {
+        console.log(`No chats in ${responsesDir()}`);
+        console.log(`Start one with: ollanet prompt <machine> "hello"`);
+        return;
+    }
+    console.log(`${pad("ID", 14)} ${pad("UPDATED", 17)} ${pad("MACHINE", 18)} ${pad("MODEL", 22)} ${pad("MSGS", 5)} TOPIC`);
+    for (const chat of chats) {
+        console.log(`${pad(chat.id, 14)} ${pad(formatWhen(chat.updated_at), 17)} ${pad(chat.machine, 18)} ${pad(chat.model, 22)} ${pad(String(chat.messages.length), 5)} ${chat.topic}`);
+    }
+    console.log(`\n${chats.length} chat(s) in ${responsesDir()}`);
+    console.log(`Continue: ollanet prompt --chat <id> "follow-up"`);
+}
+function printPreview(chat) {
+    console.log(`id:       ${chat.id}`);
+    console.log(`topic:    ${chat.topic}`);
+    console.log(`machine:  ${chat.machine}`);
+    console.log(`model:    ${chat.model}`);
+    console.log(`created:  ${chat.created_at}`);
+    console.log(`updated:  ${chat.updated_at}`);
+    if (chat.system)
+        console.log(`system:   ${chat.system}`);
+    console.log(`messages: ${chat.messages.length}`);
+    console.log("");
+    for (const msg of chat.messages) {
+        const who = msg.role.padEnd(9);
+        const when = formatWhen(msg.timestamp);
+        const body = msg.content.replace(/\s+/g, " ").trim();
+        const preview = body.length > 160 ? `${body.slice(0, 157)}...` : body;
+        console.log(`[${when}] ${who} ${preview}`);
+    }
+    console.log(`\nContinue: ollanet prompt --chat ${chat.id} "follow-up"`);
+}
+export async function main() {
+    const { json, id } = parseArgs(process.argv.slice(2));
+    if (id) {
+        const chat = await loadChat(id);
+        if (json) {
+            console.log(JSON.stringify(chat, null, 2));
+        }
+        else {
+            printPreview(chat);
+        }
+        return;
+    }
+    const chats = await listChats();
+    if (json) {
+        console.log(JSON.stringify(chats.map(summarize), null, 2));
+        return;
+    }
+    printTable(chats);
+}

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * ollanet — chat with Ollama servers on any reachable network.
+ *
+ *   ollanet scan
+ *   ollanet prompt <machine-or-ip> "hello"
+ *   ollanet chats
+ */
+const HELP = `ollanet — Ollama over your network
+
+Discover Ollama hosts on localhost, your LAN, Tailscale, or any IP/hostname
+you can reach — then chat with hash-addressed transcripts.
+
+Usage:
+  ollanet scan [--json] [--all] [--lan]
+  ollanet prompt <machine|ip> [model] <prompt...>
+  ollanet prompt --chat <hash> <prompt...>
+  ollanet chats [--json] [--id <hash>]
+
+Examples:
+  ollanet scan
+  ollanet scan --lan
+  ollanet prompt localhost "What is MagicDNS?"
+  ollanet prompt 192.168.1.50 gemma4:12b "Hello"
+  ollanet prompt --chat a1b2c3d4e5f6 "Tell me more"
+  ollanet chats
+
+Config: ~/.ollanet/config.json when installed, ./config.json in a checkout
+        (override with OLLANET_CONFIG)
+Hosts:  config.hosts, OLLANET_HOSTS, optional Tailscale + --lan
+Chats:  ~/.ollanet/responses or ./responses (override with OLLANET_RESPONSES_DIR)
+`;
+async function main() {
+    // pnpm/npm often forward a bare `--`; ignore it.
+    const argv = process.argv.slice(2).filter((arg) => arg !== "--");
+    const cmd = argv[0];
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (cmd === "-v" || cmd === "--version" || cmd === "version") {
+        const { readFile } = await import("node:fs/promises");
+        const { projectPath } = await import("./paths.js");
+        const pkg = JSON.parse(await readFile(projectPath("package.json"), "utf8"));
+        console.log(`ollanet ${pkg.version ?? "0.0.0"}`);
+        return;
+    }
+    // Strip the subcommand so command modules see their own argv.
+    process.argv = [process.argv[0] ?? "node", process.argv[1] ?? "ollanet", ...argv.slice(1)];
+    switch (cmd) {
+        case "scan":
+        case "ls-servers": {
+            const { main: run } = await import("./scan.js");
+            await run();
+            return;
+        }
+        case "prompt":
+        case "ask":
+        case "chat": {
+            const { main: run } = await import("./prompt.js");
+            await run();
+            return;
+        }
+        case "chats":
+        case "ls":
+        case "history": {
+            const { main: run } = await import("./chats.js");
+            await run();
+            return;
+        }
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            process.stderr.write(HELP);
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});
+export {};