@hiai-gg/docsmint 0.3.0

package/frontend/src/lib/hosts/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Public application hosts.
+ *
+ * These components preserve the standalone HiAi-Docs routes while allowing a
+ * product build to mount typed, additive frontend extensions.
+ */
+
+export { default as DocsmintSharedDocumentHost } from "./DocsmintSharedDocumentHost.svelte";
+export type { HiaiDocsDashboardData } from "./HiaiDocsDashboardHost.svelte";
+/** @deprecated Use DocsmintDashboardHost. */
+export {
+	default as HiaiDocsDashboardHost,
+	default as DocsmintDashboardHost,
+} from "./HiaiDocsDashboardHost.svelte";
+/** Canonical extension provider. */
+export {
+	default as HiaiDocsExtensionProvider,
+	default as DocsmintExtensionProvider,
+} from "./HiaiDocsExtensionProvider.svelte";
+export type { HiaiDocsSearchData } from "./HiaiDocsSearchHost.svelte";
+/** @deprecated Use DocsmintSearchHost. */
+export {
+	default as HiaiDocsSearchHost,
+	default as DocsmintSearchHost,
+} from "./HiaiDocsSearchHost.svelte";

package/frontend/src/lib/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Public entrypoint for the hiai-docs frontend extension package.
+ *
+ * Keep this barrel limited to SSR-safe contracts and pure helpers. Hosts such
+ * as DocsMint import this path from the published package; route modules and
+ * mutable app singletons are intentionally not part of the public surface.
+ */
+
+export type {
+	ProseMirrorDoc,
+	ProseMirrorNode,
+	SharedAttachmentObjectUrls,
+} from "./components/editor/shared-document";
+export {
+	hydrateSharedAttachmentImages,
+	renderSharedDocument,
+	sharedAttachmentHeaders,
+} from "./components/editor/shared-document";
+export {
+	createFrontendExtensions,
+	getFrontendExtensions,
+	getHiaiDocsExtensions,
+	provideFrontendExtensions,
+	setFrontendExtensions,
+	setHiaiDocsExtensions,
+} from "./extensions/context";
+export type {
+	DocTabDefinition,
+	DocTabIcon,
+	DocTabPanelProps,
+} from "./extensions/doc-tabs";
+export type {
+	CommandPaletteAction,
+	CommandPaletteActionContext,
+	CommandPaletteActionExtension,
+	DashboardWidgetExtension,
+	DashboardWidgetProps,
+	DocumentMenuAction,
+	DocumentMenuActionContext,
+	DocumentMenuActionExtension,
+	EditorActionContext,
+	EditorActionExtension,
+	ExtensionAction,
+	ExtensionIcon,
+	ExtensionVisibility,
+	ExtensionVisibilityContext,
+	FrontendExtensions,
+	HiaiDocsFrontendExtensions,
+	NavigationExtension,
+	SearchWidgetExtension,
+	SearchWidgetProps,
+	SettingsSectionExtension,
+	SettingsSectionProps,
+	SharedDocumentExtension,
+	SharedDocumentExtensionContext,
+} from "./extensions/types";
+export {
+	DocsmintDashboardHost,
+	DocsmintExtensionProvider,
+	DocsmintSearchHost,
+	DocsmintSharedDocumentHost,
+	HiaiDocsDashboardHost,
+	HiaiDocsExtensionProvider,
+	HiaiDocsSearchHost,
+} from "./hosts";

package/frontend/src/lib/stores/doc-tab-registry.svelte.ts

@@ -0,0 +1,68 @@
+/**
+ * doc-tab-registry.svelte.ts
+ *
+ * Lightweight open registry for document-page tabs.
+ *
+ * hiai-docs ships this file empty - no tabs are registered out of the box.
+ * External projects (e.g. hiai-admin, commercial forks) call registerDocTab()
+ * from their own +layout.svelte to inject custom tabs alongside the built-in
+ * editor without modifying any hiai-docs core files.
+ *
+ * Usage in an external project's layout:
+ *   import { registerDocTab } from "$lib/stores/doc-tab-registry.svelte";
+ *   import HtmlRenditionPanel from "./HtmlRenditionPanel.svelte";
+ *   registerDocTab({ id: "html-rendition", label: "HTML Preview", component: HtmlRenditionPanel });
+ *
+ * STABILITY NOTICE:
+ * The interfaces `DocTabPanelProps` and `DocTabDefinition` and functions/states
+ * `registerDocTab` and `docTabRegistry` are considered stable public APIs.
+ * Breaking changes to these will be announced as major version bumps.
+ */
+
+import type { DocTabDefinition } from "../extensions/doc-tabs";
+
+export type {
+	DocTabDefinition,
+	DocTabIcon,
+	DocTabPanelProps,
+} from "../extensions/doc-tabs";
+
+/**
+ * Reactive array of registered doc tabs.
+ * Read by the document page to render the tab bar and panels.
+ * Mutate only via registerDocTab() to guarantee idempotency.
+ */
+export const docTabRegistry: DocTabDefinition[] = $state([]);
+
+/**
+ * Create an isolated tab collection for a host-provided extension manifest.
+ * The legacy `docTabRegistry` export remains available for existing clients,
+ * while new app-shell integrations should keep their tabs request-scoped.
+ */
+export function createDocTabRegistry(
+	initial: readonly DocTabDefinition[] = [],
+): DocTabDefinition[] {
+	return [...initial];
+}
+
+/** Register a tab in an isolated collection, preserving idempotency. */
+export function registerDocTabIn(
+	registry: DocTabDefinition[],
+	tab: DocTabDefinition,
+): void {
+	if (!registry.find((existing) => existing.id === tab.id)) {
+		registry.push(tab);
+	}
+}
+
+/**
+ * Register a custom document tab.
+ *
+ * Safe to call multiple times (e.g. across HMR reloads) - duplicate ids
+ * are silently ignored so layout-level registrations do not stack up.
+ *
+ * @param tab - Tab definition to register.
+ */
+export function registerDocTab(tab: DocTabDefinition): void {
+	registerDocTabIn(docTabRegistry, tab);
+}

package/package.json

@@ -0,0 +1,178 @@
+{
+  "name": "@hiai-gg/docsmint",
+  "version": "0.3.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "The lightweight, AI-native self-hosted knowledge base — built-in RAG, hybrid semantic search, and a clean REST API for AI agents.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HiAi-gg/docsmint"
+  },
+  "homepage": "https://github.com/hiai-gg/docsmint#readme",
+  "bugs": {
+    "url": "https://github.com/hiai-gg/docsmint/issues"
+  },
+  "keywords": [
+    "knowledge-base",
+    "ai-native",
+    "wiki",
+    "markdown",
+    "ai-embeddings",
+    "rag",
+    "semantic-search",
+    "self-hosted",
+    "pgvector",
+    "ollama",
+    "local-llm",
+    "pwa",
+    "progressive-web-app",
+    "offline-knowledge-base",
+    "docsmint",
+    "outline-alternative",
+    "docmost-alternative"
+  ],
+  "main": "./packages/sdk/dist/index.js",
+  "types": "./packages/sdk/dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./packages/sdk/dist/index.js",
+      "types": "./packages/sdk/dist/index.d.ts"
+    },
+    "./sdk": {
+      "import": "./packages/sdk/dist/index.js",
+      "types": "./packages/sdk/dist/index.d.ts"
+    },
+    "./frontend": {
+      "import": "./frontend/src/lib/index.ts",
+      "types": "./frontend/src/lib/index.ts"
+    },
+    "./frontend/shared-document": {
+      "import": "./frontend/src/lib/components/editor/shared-document.ts",
+      "types": "./frontend/src/lib/components/editor/shared-document.ts"
+    },
+    "./frontend/extensions": {
+      "import": "./frontend/src/lib/extensions/types.ts",
+      "types": "./frontend/src/lib/extensions/types.ts"
+    },
+    "./frontend/hosts": {
+      "import": "./frontend/src/lib/hosts/index.ts",
+      "types": "./frontend/src/lib/hosts/index.ts"
+    },
+    "./frontend/legacy/doc-tab-registry": {
+      "import": "./frontend/src/lib/stores/doc-tab-registry.svelte.ts",
+      "types": "./frontend/src/lib/stores/doc-tab-registry.svelte.ts"
+    },
+    "./schema": {
+      "import": "./packages/db/src/schema.ts",
+      "types": "./packages/db/src/schema.ts"
+    },
+    "./db": {
+      "import": "./packages/db/src/index.ts",
+      "types": "./packages/db/src/index.ts"
+    },
+    "./db/client": {
+      "import": "./packages/db/src/client.ts",
+      "types": "./packages/db/src/client.ts"
+    },
+    "./db/with-tenant": {
+      "import": "./packages/db/src/with-tenant.ts",
+      "types": "./packages/db/src/with-tenant.ts"
+    },
+    "./backend/lib/redis": {
+      "import": "./backend/src/lib/redis-factory.ts",
+      "types": "./backend/src/lib/redis-factory.ts"
+    },
+    "./backend/lib/storage": {
+      "import": "./backend/src/lib/storage-factory.ts",
+      "types": "./backend/src/lib/storage-factory.ts"
+    },
+    "./backend/lib/logger": {
+      "import": "./backend/src/lib/logger.ts",
+      "types": "./backend/src/lib/logger.ts"
+    }
+  },
+  "bin": {
+    "docsmint": "./packages/cli/src/index.ts",
+    "docsmint-mcp": "./packages/mcp-server/src/index.ts",
+    "hiai-docs": "./packages/cli/src/index.ts",
+    "hiai-docs-mcp": "./packages/mcp-server/src/index.ts"
+  },
+  "files": [
+    "packages/sdk/dist/index.js",
+    "packages/sdk/dist/index.d.ts",
+    "packages/sdk/dist/client.js",
+    "packages/sdk/dist/client.d.ts",
+    "packages/sdk/dist/types.js",
+    "packages/sdk/dist/types.d.ts",
+    "packages/db/src/index.ts",
+    "packages/db/src/client.ts",
+    "packages/db/src/schema.ts",
+    "packages/db/src/with-tenant.ts",
+    "packages/cli/src/index.ts",
+    "packages/cli/src/client.ts",
+    "packages/cli/src/config.ts",
+    "packages/cli/src/format.ts",
+    "packages/cli/src/commands",
+    "packages/mcp-server/src/index.ts",
+    "packages/mcp-server/src/client.ts",
+    "packages/mcp-server/src/types.ts",
+    "packages/mcp-server/src/tools",
+    "backend/src/lib/redis-factory.ts",
+    "backend/src/lib/storage-factory.ts",
+    "backend/src/lib/logger.ts",
+    "frontend/src/lib/index.ts",
+    "frontend/src/lib/extensions/context.ts",
+    "frontend/src/lib/extensions/doc-tabs.ts",
+    "frontend/src/lib/extensions/resolve.ts",
+    "frontend/src/lib/extensions/types.ts",
+    "frontend/src/lib/hosts",
+    "frontend/src/lib/stores/doc-tab-registry.svelte.ts",
+    "frontend/src/lib/components/editor/shared-document.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">= 1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "docker compose up -d",
+    "build": "docker compose build",
+    "start": "docker compose up -d",
+    "stop": "docker compose down",
+    "build:sdk": "cd packages/sdk && bun run build",
+    "prepublishOnly": "cd packages/sdk && bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "commander": "^13.1.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "postgres": "^3.4.9",
+    "ioredis": "^5.4.0",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "pino": "^10.0.0",
+    "svelte": "^5.56.4"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "pino": {
+      "optional": true
+    }
+  }
+}

package/packages/cli/src/client.ts

@@ -0,0 +1,271 @@
+/**
+ * REST client for hiai-docs.
+ *
+ * Pattern mirrors @hiai-docs/mcp-server/src/client.ts: one
+ * `request()` helper handles auth headers, query encoding, and
+ * error unwrapping; the exported `client` object groups all
+ * endpoints into typed methods.
+ *
+ * Configuration comes from `./config.ts` (file + env), which
+ * differs from the MCP server's env-only approach because the CLI
+ * is interactive and benefits from a persistent config file.
+ *
+ * Bun-native. Uses global `fetch`. Throws `HiaiDocsError` on
+ * non-2xx responses with the error message extracted from the
+ * response body when possible.
+ */
+
+import { loadConfig, type Config } from "./config.js";
+
+export class HiaiDocsError extends Error {
+	constructor(
+		message: string,
+		readonly status: number,
+		readonly body: unknown,
+	) {
+		super(message);
+		this.name = "HiaiDocsError";
+	}
+}
+
+interface RequestOptions {
+	query?: Record<string, string | number | boolean | string[] | undefined>;
+	body?: unknown;
+	headers?: Record<string, string>;
+	accept?: string;
+}
+
+async function request<T>(
+	method: string,
+	path: string,
+	options: RequestOptions = {},
+): Promise<T> {
+	const cfg = loadConfig();
+	const baseUrl = cfg.url.replace(/\/+$/, "");
+	const url = new URL(path.startsWith("/") ? path : `/${path}`, `${baseUrl}/`);
+
+	if (options.query) {
+		for (const [key, value] of Object.entries(options.query)) {
+			if (value === undefined) continue;
+			if (Array.isArray(value)) {
+				if (value.length > 0) url.searchParams.set(key, value.join(","));
+			} else {
+				url.searchParams.set(key, String(value));
+			}
+		}
+	}
+
+	const headers: Record<string, string> = {
+		Accept: options.accept ?? "application/json",
+		...options.headers,
+	};
+	if (cfg.apiKey) {
+		headers["Authorization"] = `Bearer ${cfg.apiKey}`;
+	}
+
+	let body: BodyInit | undefined;
+	if (options.body !== undefined) {
+		headers["Content-Type"] = "application/json";
+		body = JSON.stringify(options.body);
+	}
+
+	const response = await fetch(url, { method, headers, body });
+
+	const contentType = response.headers.get("content-type") ?? "";
+	const isJson = contentType.includes("application/json");
+	const payload: unknown = isJson
+		? await response.json().catch(() => null)
+		: await response.text().catch(() => null);
+
+	if (!response.ok) {
+		const message =
+			(isJson &&
+			payload &&
+			typeof payload === "object" &&
+			"error" in payload
+				? String((payload as { error: unknown }).error)
+				: typeof payload === "string" && payload.length > 0
+					? payload
+					: `HTTP ${response.status} ${response.statusText}`) ||
+			`HTTP ${response.status}`;
+		throw new HiaiDocsError(message, response.status, payload);
+	}
+
+	return payload as T;
+}
+
+function joinId(...segments: string[]): string {
+	return segments.map((s) => encodeURIComponent(s)).join("/");
+}
+
+// --- Response types ----------------------------------------------------------
+
+export interface DocumentSummary {
+	id: string;
+	title: string;
+	content?: string | null;
+	folderId?: string | null;
+	folderName?: string | null;
+	createdAt: string;
+	updatedAt: string;
+	tags?: Array<{ id: string; name: string; color: string | null }>;
+}
+
+export interface DocumentDetail extends DocumentSummary {
+	ownerId: string;
+	content?: string | null;
+	contentJson?: unknown;
+	metadata?: unknown;
+}
+
+export interface Folder {
+	id: string;
+	ownerId?: string;
+	name: string;
+	parentId?: string | null;
+	createdAt?: string;
+	updatedAt?: string;
+}
+
+export interface VersionRow {
+	id: string;
+	documentId: string;
+	createdBy: string;
+	createdAt: string;
+	label?: string | null;
+	description?: string | null;
+	isSnapshot: boolean;
+	restoredFrom?: string | null;
+}
+
+export interface SnapshotRow extends VersionRow {
+	content?: string | null;
+	contentJson?: unknown;
+}
+
+export interface SearchItem {
+	id: string;
+	title: string;
+	snippet: string;
+	score: number;
+	folder_id?: string | null;
+	folder_name?: string | null;
+	created_at: string;
+	updated_at: string;
+	tags?: Array<{ id: string; name: string; color: string | null }>;
+}
+
+export interface SearchResponse {
+	items: SearchItem[];
+	total: number;
+	page: number;
+	limit: number;
+}
+
+export interface ListDocumentsResponse {
+	items: DocumentSummary[];
+	total: number;
+	page: number;
+	limit: number;
+}
+
+// --- Client ----------------------------------------------------------------
+
+export const client = {
+	search(params: {
+		query: string;
+		folder?: string;
+		tags?: string[];
+		limit?: number;
+	}): Promise<SearchResponse> {
+		return request("GET", "/api/search", {
+			query: {
+				q: params.query,
+				folder: params.folder,
+				tags: params.tags,
+				limit: params.limit,
+			},
+		});
+	},
+
+	listDocuments(params: {
+		folderId?: string;
+		tag?: string;
+		page?: number;
+		limit?: number;
+	}): Promise<ListDocumentsResponse> {
+		return request("GET", "/api/documents", { query: params });
+	},
+
+	getDocument(id: string): Promise<DocumentDetail> {
+		return request("GET", `/api/${joinId("documents", id)}`);
+	},
+
+	createDocument(input: {
+		title: string;
+		content?: string;
+		folderId?: string;
+	}): Promise<DocumentDetail> {
+		return request("POST", "/api/documents", { body: input });
+	},
+
+	updateDocument(
+		id: string,
+		input: { title?: string; content?: string; folderId?: string | null },
+	): Promise<DocumentDetail> {
+		return request("PATCH", `/api/${joinId("documents", id)}`, { body: input });
+	},
+
+	deleteDocument(id: string): Promise<{ success: boolean }> {
+		return request("DELETE", `/api/${joinId("documents", id)}`);
+	},
+
+	exportDocument(id: string): Promise<string> {
+		return request("GET", `/api/${joinId("documents", id, "export")}`, {
+			accept: "text/markdown",
+		});
+	},
+
+	createSnapshot(
+		documentId: string,
+		input: { label: string; description?: string },
+	): Promise<SnapshotRow> {
+		// The backend exposes snapshots via POST /api/documents/:id/versions
+		// with isSnapshot=true (see backend/src/api/routes/versions.ts).
+		return request(
+			"POST",
+			`/api/${joinId("documents", documentId, "versions")}`,
+			{ body: input },
+		);
+	},
+
+	listVersions(
+		documentId: string,
+		onlySnapshots?: boolean,
+	): Promise<VersionRow[]> {
+		return request(
+			"GET",
+			`/api/${joinId("documents", documentId, "versions")}`,
+			{ query: { onlySnapshots } },
+		);
+	},
+
+	restoreVersion(documentId: string, versionId: string): Promise<DocumentDetail> {
+		return request(
+			"POST",
+			`/api/${joinId("documents", documentId, "versions", versionId, "restore")}`,
+		);
+	},
+
+	listFolders(params: { parentId?: string }): Promise<Folder[]> {
+		return request("GET", "/api/folders", { query: { parentId: params.parentId } });
+	},
+
+	createFolder(input: { name: string; parentId?: string }): Promise<Folder> {
+		return request("POST", "/api/folders", { body: input });
+	},
+};
+
+export type HiaiDocsClient = typeof client;
+
+export type { Config };

package/packages/cli/src/commands/config.ts

@@ -0,0 +1,47 @@
+/**
+ * `hiai-docs config` — save or update the CLI config file.
+ *
+ * Both --url and --key are optional: with neither supplied the
+ * command just prints the current configuration. With either
+ * supplied, only the provided keys are updated (the other is
+ * preserved from the existing file or env var).
+ */
+
+import type { Command } from "commander";
+import { loadConfig, saveConfig } from "../config.js";
+import { dim, formatError, green } from "../format.js";
+
+export function registerConfig(program: Command) {
+	program
+		.command("config")
+		.description("View or update CLI configuration")
+		.option("--url <url>", "API base URL")
+		.option("--key <key>", "API key (Bearer token)")
+		.option("--show", "Print the resolved configuration and exit")
+		.action(
+			async (opts: { url?: string; key?: string; show?: boolean }) => {
+				try {
+					const current = loadConfig();
+					if (opts.show || (opts.url === undefined && opts.key === undefined)) {
+						process.stdout.write(`url:  ${current.url}\n`);
+						process.stdout.write(
+							`key:  ${current.apiKey ? `${current.apiKey.slice(0, 4)}…(redacted)` : "(unset)"}\n`,
+						);
+						process.stdout.write(
+							`${dim("Env vars HIAI_DOCS_URL / HIAI_DOCS_API_KEY override the file.")}\n`,
+						);
+						return;
+					}
+					const next = {
+						url: opts.url ?? current.url,
+						apiKey: opts.key ?? current.apiKey,
+					};
+					saveConfig(next);
+					process.stdout.write(`${green("✓")} Configuration saved.\n`);
+				} catch (err) {
+					process.stderr.write(`${formatError(err)}\n`);
+					process.exitCode = 1;
+				}
+			},
+		);
+}

package/packages/cli/src/commands/create.ts

@@ -0,0 +1,35 @@
+/**
+ * `hiai-docs create` — create a new document.
+ *
+ * Optional `--content` lets you inline markdown from the CLI; if you
+ * pipe a file (`cat spec.md | hiai-docs create --title "Spec"` —
+ * reserved for a future stdin flag) you'd extend this command.
+ */
+
+import type { Command } from "commander";
+import { client, type HiaiDocsClient } from "../client.js";
+import { formatError } from "../format.js";
+
+export function registerCreate(program: Command, _getClient: () => HiaiDocsClient) {
+	program
+		.command("create")
+		.description("Create a new document")
+		.requiredOption("--title <title>", "Document title")
+		.option("-c, --content <markdown>", "Initial markdown content")
+		.option("-f, --folder <uuid>", "Place in folder")
+		.action(
+			async (opts: { title: string; content?: string; folder?: string }) => {
+				try {
+					const doc = await client.createDocument({
+						title: opts.title,
+						content: opts.content,
+						folderId: opts.folder,
+					});
+					process.stdout.write(`${doc.id}\n`);
+				} catch (err) {
+					process.stderr.write(`${formatError(err)}\n`);
+					process.exitCode = 1;
+				}
+			},
+		);
+}