@hiai-gg/docsmint 0.3.0

package/LICENSE

@@ -0,0 +1,171 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,348 @@
+# HiAi-Docs / DocsMint
+
+**A self-hosted, AI-native knowledge workspace for people, applications, and agents.**
+
+HiAi-Docs is the open-source module and repository. **DocsMint** is the current
+product branding used by the standalone installable web application. Typed
+frontend hosts and extension contracts support self-hosted customization.
+
+HiAi-Docs stores documents in a structured JSON editor model first. Markdown is
+the convenient second format for editing, importing, and exporting content.
+Automatic chunking, 1024-dimensional embeddings, multilingual hybrid search,
+and GraphRAG make the same knowledge base useful to people, applications, and
+agents through the web application, REST API, TypeScript SDK, CLI, and MCP
+server.
+
+[![Apache-2.0 License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/hiai-gg/docsmint?sort=semver)](https://github.com/hiai-gg/docsmint/releases)
+[![Stars](https://img.shields.io/github/stars/hiai-gg/docsmint)](https://github.com/hiai-gg/docsmint/stargazers)
+[![CI](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml/badge.svg)](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)
+[![Bun](https://img.shields.io/badge/Runtime-Bun_1.3-black?logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Svelte](https://img.shields.io/badge/Svelte-5.x-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev)
+[![Elysia](https://img.shields.io/badge/Elysia-1.4-lightgrey?logo=elysia&logoColor=white)](https://elysiajs.com)
+[![Tailwind_CSS](https://img.shields.io/badge/Tailwind_CSS-v4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
+[![Drizzle_ORM](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle&logoColor=black)](https://orm.drizzle.team)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+<img width="1920" height="974" alt="DocsMint installable document workspace" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />
+
+## Why HiAi-Docs?
+
+- **Write naturally** in a rich visual editor or raw Markdown.
+- **Find meaning, not only keywords** with exact, lexical, fuzzy, vector,
+  multilingual expansion, and graph retrieval fused through RRF.
+- **Keep retrieval current** with automatic, incremental chunking and
+  re-embedding after document or metadata changes.
+- **Connect agents directly** through REST, a typed SDK, CLI, or MCP.
+- **Control access** with global keys or category-scoped `read`, `edit`, and
+  `write` permissions.
+- **Own the full stack**: application data, vectors, graph, queue, and files run
+  on infrastructure you control.
+
+## What is new in the 0.3.0 release line?
+
+- **Installable Progressive Web App (PWA)** with a manifest, service worker,
+  responsive mobile shell, install prompt, update safety, and an offline
+  fallback shell.
+- **Offline document access** through identity-partitioned IndexedDB/Dexie
+  snapshots. Offline mode is cached read plus explicit local drafts; reconnect
+  never silently replays mutations.
+- **Explicit local drafts** with local autosave, review/apply, optimistic
+  concurrency (`expectedUpdatedAt`), and actionable conflict handling.
+- **Composable host integration** with typed dashboard/search hosts and
+  extension slots. Standalone HiAi-Docs remains owner-scoped.
+- **Mobile-first editor polish** including a single responsive sidebar, safe
+  PWA updates, raw Markdown auto-height, and accessible narrow-screen controls.
+
+Search terms: installable self-hosted PWA knowledge base, offline document
+reading, local drafts, semantic multilingual search, GraphRAG, MCP, TypeScript
+SDK, CLI, and frontend extension hosts.
+
+For self-hosted customization, see [PWA hosting](docs/PWA_HOSTING.md) and
+[extension points](docs/EXTENDING.md).
+
+## Fastest installation: give this prompt to your agent
+
+If you are installing HiAi-Docs through an AI coding agent, use this path first.
+It keeps the setup to Docker plus one provider choice and avoids unnecessary
+source-code changes.
+
+```text
+Install HiAi-Docs from https://github.com/HiAi-gg/docsmint.
+Verify Docker and Docker Compose v2, clone the repository, and run
+`bash scripts/quickstart.sh`. Do not print or commit .env. Ask me to enter only
+an OpenRouter key or select Ollama, then run quickstart again. Verify
+http://localhost:50701, http://localhost:50700/api/health, and
+`docker compose ps`. Do not replace Bun, rewrite migrations, disable GraphRAG,
+or delete volumes.
+```
+
+After startup, open **http://localhost:50701** and create the first account.
+For manual installation, use the Docker quickstart below.
+
+## Quickstart
+
+### Requirements
+
+- Docker Engine or Docker Desktop
+- Docker Compose v2
+- One of:
+  - an [OpenRouter](https://openrouter.ai/) API key; or
+  - a local [Ollama](https://ollama.com/) instance
+
+### Start with Docker
+
+```bash
+git clone https://github.com/HiAi-gg/docsmint.git
+cd docsmint
+bash scripts/quickstart.sh
+```
+On its first run, the script creates an ignored root `.env`, generates the
+database, authentication, and storage secrets, builds the PostgreSQL image,
+applies migrations, and starts the complete application.
+
+For OpenRouter, add one value to `.env` and run the script again:
+
+```dotenv
+OPENROUTER_API_KEY=sk-or-your-key
+```
+For Ollama, select the local provider instead:
+
+```dotenv
+AI_PROVIDER=ollama
+OLLAMA_PORT=11434
+```
+Then make sure the configured local models are available:
+
+```bash
+ollama pull bge-m3
+ollama pull qwen3:8b
+bash scripts/quickstart.sh
+```
+Open **http://localhost:50701**. The API health endpoint is
+**http://localhost:50700/api/health**.
+
+### First use
+
+1. Create your account in the web application.
+2. Create a category or folder and add or import a document.
+3. Wait for the document pipeline to finish chunking and embedding.
+4. Search using an exact phrase, a related concept, an alternate language, or
+   a misspelling.
+5. Open **Settings → API** when you want to connect a CLI, MCP client, or
+   external application.
+
+The canonical local ports are:
+
+| Service | Port |
+|---|---:|
+| Web application | `50701` |
+| REST API | `50700` |
+| PostgreSQL | `5437` |
+| Redis | `6384` |
+| SeaweedFS S3 gateway | `50702` |
+| SeaweedFS filer UI | `50703` |
+
+See [Deployment](docs/DEPLOYMENT.md) for domains, TLS, provider tuning,
+backups, and production operation.
+
+## Use HiAi-Docs from the terminal
+
+The published package includes the CLI. It connects to an already running
+HiAi-Docs server; installing it does not deploy the server.
+
+```bash
+bunx --package @hiai-gg/docsmint docsmint init \
+  --url http://localhost:50700 \
+  --key 'your-global-or-category-key'
+
+bunx --package @hiai-gg/docsmint docsmint search "project architecture"
+bunx --package @hiai-gg/docsmint docsmint list
+bunx --package @hiai-gg/docsmint docsmint read <document-id>
+bunx --package @hiai-gg/docsmint docsmint create \
+  --title "Release notes" --content "# Version 0.2.9"
+```
+Credentials can also be supplied through `HIAI_DOCS_URL` and
+`HIAI_DOCS_API_KEY`. See the [CLI guide](packages/cli/README.md) for every
+command and configuration precedence.
+
+## Connect an MCP client
+
+HiAi-Docs exposes document search, reading, creation, updates, folders,
+snapshots, history, and export as MCP tools.
+
+```json
+{
+  "mcpServers": {
+    "docsmint": {
+      "command": "bunx",
+      "args": ["--package", "@hiai-gg/docsmint", "docsmint-mcp"],
+      "env": {
+        "HIAI_DOCS_URL": "http://localhost:50700",
+        "HIAI_DOCS_API_KEY": "your-global-or-category-key"
+      }
+    }
+  }
+}
+```
+Run the server directly to verify the installation:
+
+```bash
+bunx --package @hiai-gg/docsmint docsmint-mcp
+```
+The server uses stdio and works with MCP-capable clients such as Claude
+Desktop, Cursor, and coding agents that accept standard MCP configuration. See
+the [MCP guide](packages/mcp-server/README.md) for its ten tools and routes.
+
+## Agent skills after installation
+
+The MCP tools are the recommended portable agent skills. A category-bound agent
+can receive only the knowledge and operations it needs; a trusted personal
+agent can use a global key. Agents do not need database or filesystem access.
+After startup, create an API key in **Settings → API** and add the MCP block
+above to the agent client. For custom agent workflows, use the same key through
+the CLI, SDK, or REST API.
+
+## TypeScript SDK
+
+```bash
+bun add @hiai-gg/docsmint
+```
+```ts
+import { DocsClient } from "@hiai-gg/docsmint";
+
+const docs = new DocsClient({
+  baseUrl: "http://localhost:50700",
+  apiKey: process.env.HIAI_DOCS_API_KEY,
+});
+
+const created = await docs.createDoc({
+  title: "Meeting notes",
+  content: "# Agenda",
+});
+
+const results = await docs.search("what did we decide?");
+console.log(created.id, results.items);
+```
+The SDK is a typed `fetch` client with retries for transient failures. See the
+[SDK reference](packages/sdk/README.md) and [REST API](docs/API.md).
+
+## API keys and integrations
+
+Create and revoke integration keys from **Settings → API**.
+
+| Credential | Intended use | Access |
+|---|---|---|
+| Global API key | Trusted owner-wide CLI, MCP, SDK, or service | All owner content |
+| Category key | Least-privilege agent or product integration | One category with selected permissions |
+| Operator key | Administration and reindex operations | `/api/admin/*` only |
+
+Category permissions are explicit and non-hierarchical:
+
+- `read` permits list, read, search, and export;
+- `edit` permits updates to existing content, attachments, and versions;
+- `write` permits create, move, delete, share, and publish operations.
+
+Combine permissions when an integration needs more than one capability.
+API-key lifecycle operations require the owning browser session; an API key
+cannot create or elevate another key. Server-to-server integrations are not
+affected by browser CORS. Browser integrations must add their exact origin to
+`CORS_ORIGINS`.
+
+## What is included?
+
+```text
+frontend/          SvelteKit workspace and TipTap editor
+backend/           Elysia REST API, search, workers, and authentication
+packages/db/       Drizzle schema and migrations
+packages/sdk/      Typed API client
+packages/cli/      Terminal client
+packages/mcp-server/  MCP stdio server
+postgres/          PostgreSQL image with vector and graph extensions
+```
+The Docker deployment runs:
+
+- **Web** — document editor, folders, categories, sharing, settings, and search;
+- **API** — documents, attachments, versions, keys, search, and administration;
+- **PostgreSQL 18** — relational data, pgvector/pgvectorscale vectors, and the
+  Apache AGE graph in one database;
+- **Redis 8** — BullMQ queues, caching, retries, and job recovery;
+- **SeaweedFS** — S3-compatible attachment storage.
+
+## How search works
+
+Every document save schedules background work. Content is chunked, changed
+chunks are embedded, and the completed generation is activated atomically. The
+previous valid generation remains searchable if a provider call fails.
+
+Search combines exact title matches, multilingual lexical search, typo-tolerant
+fuzzy matching, semantic vectors, adaptive query expansion, and Apache AGE
+graph neighbors. Reciprocal rank fusion combines the channels without allowing
+one weak provider result to dominate. Authorization is applied before retrieval
+and again before results are returned.
+
+GraphRAG is part of the normal search path in the reference configuration. It
+extracts entities after embeddings are ready and finds related documents beyond
+direct keyword or vector similarity. It degrades gracefully when an external
+model is unavailable.
+
+For pipeline internals and tuning, see [Architecture](docs/ARCHITECTURE.md) and
+[Deployment](docs/DEPLOYMENT.md).
+
+## Stack
+
+- Bun, TypeScript, Elysia, Zod, and Pino
+- Svelte 5, SvelteKit, Tailwind CSS, and TipTap
+- Better Auth and Drizzle ORM
+- PostgreSQL 18, pgvector, pgvectorscale, and Apache AGE
+- Redis 8 and BullMQ
+- SeaweedFS with its S3-compatible API
+- OpenAI-compatible providers through OpenRouter or local Ollama
+
+## Comparison
+
+HiAi-Docs overlaps with several excellent open-source knowledge tools, but its
+focus is a compact knowledge runtime shared equally by humans and agents.
+
+| Project | Primary strength | Difference from HiAi-Docs |
+|---|---|---|
+| [Outline](https://github.com/outline/outline) | Polished team wiki and collaboration | HiAi-Docs emphasizes built-in retrieval, GraphRAG, scoped agent access, CLI, and MCP |
+| [Docmost](https://github.com/docmost/docmost) | Collaborative wiki and real-time editing | HiAi-Docs centers automatic embeddings and agent-facing integration surfaces |
+| [AppFlowy](https://github.com/AppFlowy-IO/AppFlowy) | Broad local-first productivity workspace | HiAi-Docs is narrower: a self-hosted document and retrieval service |
+| [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) | Chat-oriented RAG over imported sources | HiAi-Docs starts with the editable knowledge base and exposes it to many clients |
+| [Danswer](https://github.com/danswer-ai/danswer) / Onyx | Enterprise search across external connectors | HiAi-Docs owns and edits its native corpus rather than primarily indexing other systems |
+
+This is a product-positioning summary, not a claim that every listed project
+lacks a feature. Check each project's current documentation when choosing a
+deployment.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Product usage](docs/USAGE.md)
+- [REST API](docs/API.md) and [OpenAPI JSON](docs/openapi.json)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Deployment and operations](docs/DEPLOYMENT.md)
+- [Extension points](docs/EXTENDING.md)
+- [Maintainer release flow](docs/RELEASING.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## Development
+
+```bash
+bun install
+bun run lint
+bun run typecheck
+bun run test
+bun run build
+```
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Please
+report vulnerabilities through [SECURITY.md](SECURITY.md), not a public issue.
+
+## License
+
+HiAi-Docs / DocsMint is released under the [Apache License 2.0](LICENSE).
+
+Part of the [HiAi](https://hiai.gg) open-source ecosystem.

package/backend/src/lib/logger.ts

@@ -0,0 +1,18 @@
+import pino from "pino";
+
+// Read env directly to avoid circular dependency with config.ts
+const level = (process.env.LOG_LEVEL ?? "info") as
+	| "trace"
+	| "debug"
+	| "info"
+	| "warn"
+	| "error"
+	| "fatal";
+const isDev = process.env.NODE_ENV === "development";
+
+export const logger = pino({
+	level,
+	transport: isDev
+		? { target: "pino-pretty", options: { colorize: true } }
+		: undefined,
+});

package/backend/src/lib/redis-factory.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure Redis factory — no module-eval side effects.
+ *
+ * This module MUST NOT import `./config` (which calls `envSchema.parse` and
+ * `process.exit(1)` at import time). External consumers (e.g. docsmint)
+ * import this through the npm export `@hiai-gg/docsmint/backend/lib/redis`
+ * to call `createRedis(cfg)` with their own config; pulling hiai-docs'
+ * env-validation into their process would crash it on the first missing
+ * variable.
+ *
+ * The singleton that powers hiai-docs' own runtime lives in `./redis.ts`
+ * and imports this factory.
+ */
+import Redis from "ioredis";
+import { logger } from "./logger";
+
+export interface RedisConfig {
+	url: string;
+	maxRetriesPerRequest: number;
+}
+
+export function createRedis(cfg: RedisConfig): Redis {
+	const instance = new Redis(cfg.url, {
+		maxRetriesPerRequest: cfg.maxRetriesPerRequest,
+		retryStrategy(times) {
+			const delay = Math.min(times * 200, 2000);
+			return delay;
+		},
+	});
+
+	instance.on("error", (err) => {
+		logger.error({ err }, "Redis connection error");
+	});
+
+	instance.on("connect", () => {
+		logger.info("Redis connected");
+	});
+
+	return instance;
+}

package/backend/src/lib/storage-factory.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure S3 (SeaweedFS) factory — no module-eval side effects.
+ *
+ * This module MUST NOT import `./config` (which calls `envSchema.parse` and
+ * `process.exit(1)` at import time). External consumers (e.g. docsmint)
+ * import this through the npm export `@hiai-gg/docsmint/backend/lib/storage`
+ * to call `createObjectStorageClient(cfg)` with their own config; pulling
+ * hiai-docs' env-validation into their process would crash it on the first
+ * missing variable.
+ *
+ * The singletons that power hiai-docs' own runtime live in `./storage.ts`
+ * and import this factory.
+ */
+import { S3Client } from "@aws-sdk/client-s3";
+import { logger } from "./logger";
+
+export interface ObjectStorageConfig {
+	endpoint: string;
+	port: number;
+	accessKey: string;
+	secretKey: string;
+	useSSL: boolean;
+	region: string;
+	forcePathStyle: boolean;
+}
+
+export function createObjectStorageClient(cfg: ObjectStorageConfig): S3Client {
+	return new S3Client({
+		endpoint: cfg.useSSL
+			? `https://${cfg.endpoint}:${cfg.port}`
+			: `http://${cfg.endpoint}:${cfg.port}`,
+		region: cfg.region,
+		credentials: {
+			accessKeyId: cfg.accessKey,
+			secretAccessKey: cfg.secretKey,
+		},
+		forcePathStyle: cfg.forcePathStyle,
+		requestChecksumCalculation: "WHEN_REQUIRED",
+		responseChecksumValidation: "WHEN_REQUIRED",
+	});
+}
+
+export async function ensureBucket(
+	client: S3Client,
+	bucket: string,
+): Promise<void> {
+	const { HeadBucketCommand, CreateBucketCommand } = await import(
+		"@aws-sdk/client-s3"
+	);
+	try {
+		await client.send(new HeadBucketCommand({ Bucket: bucket }));
+	} catch {
+		await client.send(new CreateBucketCommand({ Bucket: bucket }));
+		logger.info({ bucket }, "Created storage bucket");
+	}
+}