@hiai-gg/docsmint 0.3.4 → 0.3.5

package/dist/backend-launcher.d.ts

@@ -0,0 +1,40 @@
+/** Server-only launcher for the bundled DocsMint backend runtime. */
+export type DocsmintBackendEnvironment = Readonly<Record<string, string | undefined>>;
+export type LaunchDocsmintBackendOptions = Readonly<{
+    cwd?: string;
+    env?: DocsmintBackendEnvironment;
+    healthUrl?: string;
+    startupTimeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+}>;
+export type DocsmintBackendProcess = Readonly<{
+    pid: number;
+    exited: Promise<number>;
+    kill(signal: "SIGTERM" | "SIGKILL"): void;
+}>;
+export type DocsmintBackendSpawnSpec = Readonly<{
+    command: readonly string[];
+    cwd?: string;
+    env: Readonly<Record<string, string>>;
+}>;
+export type DocsmintBackendLauncherRuntime = Readonly<{
+    executable: string;
+    launcherModuleUrl?: string | URL;
+    spawn(spec: DocsmintBackendSpawnSpec): DocsmintBackendProcess;
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+}>;
+export type DocsmintBackendHandle = Readonly<{
+    pid: number;
+    ready: Promise<void>;
+    exited: Promise<number>;
+    stop(): Promise<void>;
+}>;
+export type DocsmintBackendLauncher = Readonly<{
+    launch(options?: LaunchDocsmintBackendOptions): DocsmintBackendHandle;
+}>;
+export declare function resolveDocsmintBackendEntrypoint(launcherModuleUrl?: string | URL): URL;
+export declare function createDocsmintBackendLauncher(runtime: DocsmintBackendLauncherRuntime): DocsmintBackendLauncher;
+export declare function launchDocsmintBackend(options?: LaunchDocsmintBackendOptions): DocsmintBackendHandle;

package/dist/backend-launcher.js

@@ -0,0 +1,114 @@
+/** Server-only launcher for the bundled DocsMint backend runtime. */
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 200;
+const DEFAULT_API_PORT = "50700";
+function assertPositiveMilliseconds(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+}
+function immutableEnvironment(overrides = {}) {
+    const merged = {};
+    for (const [key, value] of Object.entries({ ...process.env, ...overrides })) {
+        if (typeof value === "string")
+            merged[key] = value;
+    }
+    return Object.freeze(merged);
+}
+export function resolveDocsmintBackendEntrypoint(launcherModuleUrl = import.meta.url) {
+    return new URL("./backend/index.js", launcherModuleUrl);
+}
+function defaultRuntime() {
+    if (typeof Bun === "undefined") {
+        throw new Error("DocsMint backend launcher requires the Bun runtime");
+    }
+    return {
+        executable: Bun.argv[0] ?? "bun",
+        spawn(spec) {
+            const child = Bun.spawn({
+                cmd: [...spec.command],
+                ...(spec.cwd ? { cwd: spec.cwd } : {}),
+                env: { ...spec.env },
+                stdout: "inherit",
+                stderr: "inherit",
+            });
+            return {
+                pid: child.pid,
+                exited: child.exited,
+                kill(signal) {
+                    child.kill(signal);
+                },
+            };
+        },
+        fetch: (input, init) => fetch(input, init),
+        now: Date.now,
+        sleep: (milliseconds) => Bun.sleep(milliseconds),
+    };
+}
+export function createDocsmintBackendLauncher(runtime) {
+    const now = runtime.now ?? Date.now;
+    const sleep = runtime.sleep ?? ((milliseconds) => Bun.sleep(milliseconds));
+    return Object.freeze({
+        launch(options = {}) {
+            const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+            const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+            assertPositiveMilliseconds(startupTimeoutMs, "startupTimeoutMs");
+            assertPositiveMilliseconds(pollIntervalMs, "pollIntervalMs");
+            if (options.signal?.aborted) {
+                throw new DOMException("Backend launch aborted", "AbortError");
+            }
+            const env = immutableEnvironment(options.env);
+            const port = env.API_PORT ?? DEFAULT_API_PORT;
+            const healthUrl = options.healthUrl ?? `http://127.0.0.1:${port}/api/health`;
+            const entrypoint = resolveDocsmintBackendEntrypoint(runtime.launcherModuleUrl ?? import.meta.url);
+            const child = runtime.spawn(Object.freeze({
+                command: Object.freeze([runtime.executable, entrypoint.pathname]),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+                env,
+            }));
+            let stopped = false;
+            const stop = async () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                child.kill("SIGTERM");
+            };
+            const ready = (async () => {
+                const deadline = now() + startupTimeoutMs;
+                try {
+                    while (now() <= deadline) {
+                        if (options.signal?.aborted) {
+                            throw new DOMException("Backend launch aborted", "AbortError");
+                        }
+                        try {
+                            const response = await runtime.fetch(healthUrl, {
+                                signal: options.signal,
+                            });
+                            if (response.ok)
+                                return;
+                        }
+                        catch (error) {
+                            if (options.signal?.aborted)
+                                throw error;
+                        }
+                        await sleep(pollIntervalMs);
+                    }
+                    throw new Error(`DocsMint backend did not become ready within ${startupTimeoutMs}ms`);
+                }
+                catch (error) {
+                    await stop();
+                    throw error;
+                }
+            })();
+            return Object.freeze({
+                pid: child.pid,
+                ready,
+                exited: child.exited,
+                stop,
+            });
+        },
+    });
+}
+export function launchDocsmintBackend(options = {}) {
+    return createDocsmintBackendLauncher(defaultRuntime()).launch(options);
+}

package/dist/storage-quota.d.ts

@@ -0,0 +1,56 @@
+/** Server-only, persistence-agnostic storage quota contract. */
+export type StorageQuotaContext = Readonly<{
+    actorUserId: string;
+    requestId: string;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}>;
+export type StorageQuotaReservationRequest = StorageQuotaContext & Readonly<{
+    bytes: number;
+}>;
+export type StorageQuotaReservation = Readonly<{
+    status: "reserved" | "already_reserved";
+    reservationId: string;
+    reservedBytes: number;
+    usageBytes: number;
+    limitBytes: number;
+    expiresAt: string;
+}>;
+export type StorageQuotaRejection = Readonly<{
+    status: "rejected";
+    usageBytes: number;
+    limitBytes: number;
+    requestedBytes: number;
+}>;
+export type StorageQuotaCommitRequest = StorageQuotaContext & Readonly<{
+    reservationId: string;
+    actualBytes: number;
+}>;
+export type StorageQuotaReleaseRequest = StorageQuotaContext & Readonly<{
+    reservationId: string;
+}>;
+export type StorageQuotaCommitResult = Readonly<{
+    status: "committed" | "already_committed";
+}>;
+export type StorageQuotaReleaseResult = Readonly<{
+    status: "released" | "already_released" | "not_found";
+}>;
+export type StorageQuotaAdapter = Readonly<{
+    /** Must atomically check usage and create an idempotent reservation. */
+    reserve(request: StorageQuotaReservationRequest): Promise<StorageQuotaReservation | StorageQuotaRejection>;
+    commit(request: StorageQuotaCommitRequest): Promise<StorageQuotaCommitResult>;
+    release(request: StorageQuotaReleaseRequest): Promise<StorageQuotaReleaseResult>;
+}>;
+export type StorageQuotaService = Readonly<{
+    reserve(request: StorageQuotaReservationRequest): Promise<StorageQuotaReservation>;
+    commit(request: StorageQuotaCommitRequest): Promise<StorageQuotaCommitResult>;
+    release(request: StorageQuotaReleaseRequest): Promise<StorageQuotaReleaseResult>;
+}>;
+export declare class StorageQuotaExceededError extends Error {
+    readonly code: "STORAGE_QUOTA_EXCEEDED";
+    readonly usageBytes: number;
+    readonly limitBytes: number;
+    readonly requestedBytes: number;
+    constructor(rejection: StorageQuotaRejection);
+}
+export declare function createStorageQuotaService(adapter: StorageQuotaAdapter): StorageQuotaService;

package/dist/storage-quota.js

@@ -0,0 +1,91 @@
+/** Server-only, persistence-agnostic storage quota contract. */
+export class StorageQuotaExceededError extends Error {
+    code = "STORAGE_QUOTA_EXCEEDED";
+    usageBytes;
+    limitBytes;
+    requestedBytes;
+    constructor(rejection) {
+        super("Storage quota exceeded");
+        this.name = "StorageQuotaExceededError";
+        this.usageBytes = rejection.usageBytes;
+        this.limitBytes = rejection.limitBytes;
+        this.requestedBytes = rejection.requestedBytes;
+    }
+}
+function assertContext(context) {
+    for (const [name, value] of [
+        ["actorUserId", context.actorUserId],
+        ["requestId", context.requestId],
+        ["idempotencyKey", context.idempotencyKey],
+    ]) {
+        if (!value.trim())
+            throw new TypeError(`${name} must not be empty`);
+    }
+    if (context.signal?.aborted) {
+        throw new DOMException("Storage quota operation aborted", "AbortError");
+    }
+}
+function assertPositiveBytes(bytes, name) {
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+}
+function assertNonnegativeBytes(bytes, name) {
+    if (!Number.isSafeInteger(bytes) || bytes < 0) {
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function assertReservation(result) {
+    assertReservationId(result.reservationId);
+    assertPositiveBytes(result.reservedBytes, "reservedBytes");
+    assertNonnegativeBytes(result.usageBytes, "usageBytes");
+    assertNonnegativeBytes(result.limitBytes, "limitBytes");
+    if (Number.isNaN(Date.parse(result.expiresAt))) {
+        throw new TypeError("expiresAt must be an ISO-compatible timestamp");
+    }
+}
+function assertRejection(result) {
+    assertNonnegativeBytes(result.usageBytes, "usageBytes");
+    assertNonnegativeBytes(result.limitBytes, "limitBytes");
+    assertPositiveBytes(result.requestedBytes, "requestedBytes");
+}
+function assertReservationId(value) {
+    if (!value.trim())
+        throw new TypeError("reservationId must not be empty");
+}
+export function createStorageQuotaService(adapter) {
+    return Object.freeze({
+        async reserve(request) {
+            assertContext(request);
+            assertPositiveBytes(request.bytes, "bytes");
+            const result = await adapter.reserve(Object.freeze({ ...request }));
+            if (result.status === "rejected") {
+                assertRejection(result);
+                throw new StorageQuotaExceededError(result);
+            }
+            assertReservation(result);
+            return Object.freeze({ ...result });
+        },
+        async commit(request) {
+            assertContext(request);
+            assertReservationId(request.reservationId);
+            assertPositiveBytes(request.actualBytes, "actualBytes");
+            const result = await adapter.commit(Object.freeze({ ...request }));
+            if (result.status !== "committed" && result.status !== "already_committed") {
+                throw new TypeError("Storage quota adapter returned an invalid commit status");
+            }
+            return Object.freeze({ ...result });
+        },
+        async release(request) {
+            assertContext(request);
+            assertReservationId(request.reservationId);
+            const result = await adapter.release(Object.freeze({ ...request }));
+            if (result.status !== "released" &&
+                result.status !== "already_released" &&
+                result.status !== "not_found") {
+                throw new TypeError("Storage quota adapter returned an invalid release status");
+            }
+            return Object.freeze({ ...result });
+        },
+    });
+}

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@hiai-gg/docsmint",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "type": "module",
   "browser": {
+    "./dist/backend-launcher.js": false,
     "./dist/lifecycle.js": false,
+    "./dist/storage-quota.js": false,
     "./dist/workspace.js": false
   },
   "license": "Apache-2.0",
@@ -61,6 +63,16 @@
       "import": "./dist/workspace.js",
       "types": "./dist/workspace.d.ts"
     },
+    "./backend/launcher": {
+      "browser": "./dist/server-only-browser-entry.js",
+      "import": "./dist/backend-launcher.js",
+      "types": "./dist/backend-launcher.d.ts"
+    },
+    "./storage-quota": {
+      "browser": "./dist/server-only-browser-entry.js",
+      "import": "./dist/storage-quota.js",
+      "types": "./dist/storage-quota.d.ts"
+    },
     "./frontend/dashboard": {
       "import": "./dist/frontend/dashboard.js",
       "types": "./dist/frontend/dashboard.d.ts"

package/packages/cli/src/index.ts

@@ -24,7 +24,7 @@ import { registerSearch } from "./commands/search.js";
 import { registerSnapshot } from "./commands/snapshot.js";
 import { registerUpdate } from "./commands/update.js";
 
-const VERSION = "0.3.4";
+const VERSION = "0.3.5";
 
 const program = new Command();
 program

package/packages/mcp-server/src/index.ts

@@ -35,7 +35,7 @@ interface McpToolResult {
 
 const server = new McpServer({
 	name: "hiai-docs",
-	version: "0.3.4",
+	version: "0.3.5",
 });
 
 /**