ysk-server-core 1.0.0

package/dist/config/schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Configuration load / validate for YSK Server control plane.
+ */
+import { type SetupConfigDto } from 'ysk-server-shared';
+export interface YskConfig {
+    version: number;
+    product: 'ysk-server';
+    dataDir: string;
+    listenHost: string;
+    listenPort: number;
+    adminUsername: string;
+    locale: string;
+    setupCompleted: boolean;
+    createdAt: string;
+    /**
+     * Control-plane TLS (panel HTTPS). When enabled and cert/key files exist,
+     * `ysk-server serve` binds HTTPS on listenPort.
+     */
+    tlsEnabled?: boolean;
+    tlsCertPath?: string;
+    tlsKeyPath?: string;
+    /** Domain used for panel LE / URL hints (e.g. demo.ysk.hk) */
+    panelDomain?: string;
+    /**
+     * When TLS is on, also bind plain HTTP on this port (default listenPort-1 if > 1024).
+     * Used for migration / health; optional redirect to HTTPS.
+     */
+    httpListenPort?: number;
+    /** If dual HTTP is up, 301 to HTTPS (default true) */
+    tlsHttpRedirect?: boolean;
+    /**
+     * When true (recommended for bootstrap / production IP install),
+     * never bind a companion plain-HTTP listener — HTTPS only.
+     */
+    tlsHttpsOnly?: boolean;
+}
+/**
+ * Validate and normalize a setup DTO into a persisted config object.
+ */
+export declare function buildConfigFromSetup(input: Partial<SetupConfigDto> & {
+    dataDir: string;
+}): YskConfig;
+/**
+ * Parse raw JSON config and validate shape.
+ */
+export declare function parseConfig(raw: unknown): YskConfig;
+/** Default companion HTTP port when TLS is on (avoid privileged 80). */
+export declare function defaultHttpListenPort(httpsPort: number): number;
+/** Merge TLS / panel fields into existing config (persist-safe). */
+export declare function mergePanelTlsConfig(base: YskConfig, patch: {
+    tlsEnabled?: boolean;
+    tlsCertPath?: string | null;
+    tlsKeyPath?: string | null;
+    panelDomain?: string | null;
+    tlsHttpsOnly?: boolean;
+    listenHost?: string;
+}): YskConfig;
+//# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAwB,KAAK,cAAc,EAAK,MAAM,mBAAmB,CAAC;AAEjF,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAYD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAuBpG;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAqCnD;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EACf,KAAK,EAAE;IACL,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,SAAS,CAqBX"}

package/dist/config/schema.js

@@ -0,0 +1,112 @@
+/**
+ * Configuration load / validate for YSK Server control plane.
+ */
+import { ErrorCodes, YskError, tl } from 'ysk-server-shared';
+const DEFAULTS = {
+    version: 1,
+    product: 'ysk-server',
+    listenHost: '127.0.0.1',
+    /** 4-digit control-plane port; avoid common 3000/5173/8080/8787 */
+    listenPort: 9287,
+    adminUsername: 'admin',
+    locale: 'zh-HK',
+};
+/**
+ * Validate and normalize a setup DTO into a persisted config object.
+ */
+export function buildConfigFromSetup(input) {
+    if (!input.dataDir || typeof input.dataDir !== 'string') {
+        throw new YskError(ErrorCodes.CONFIG_INVALID, tl('notes.auto.n1402'), { httpStatus: 400 });
+    }
+    const port = input.listenPort ?? DEFAULTS.listenPort;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new YskError(ErrorCodes.CONFIG_INVALID, tl('notes.auto.t0001', { v0: (port) }), { httpStatus: 400 });
+    }
+    const host = input.listenHost ?? DEFAULTS.listenHost;
+    if (!host || typeof host !== 'string') {
+        throw new YskError(ErrorCodes.CONFIG_INVALID, tl('notes.auto.n1403'), { httpStatus: 400 });
+    }
+    return {
+        version: DEFAULTS.version,
+        product: DEFAULTS.product,
+        dataDir: input.dataDir,
+        listenHost: host,
+        listenPort: port,
+        adminUsername: input.adminUsername ?? DEFAULTS.adminUsername,
+        locale: input.locale ?? DEFAULTS.locale,
+        setupCompleted: true,
+        createdAt: new Date().toISOString(),
+    };
+}
+/**
+ * Parse raw JSON config and validate shape.
+ */
+export function parseConfig(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new YskError(ErrorCodes.CONFIG_INVALID, tl('notes.auto.n1372'), { httpStatus: 400 });
+    }
+    const o = raw;
+    if (o.product !== 'ysk-server') {
+        throw new YskError(ErrorCodes.CONFIG_INVALID, tl('notes.auto.n1371'), {
+            httpStatus: 400,
+        });
+    }
+    if (typeof o.dataDir !== 'string' || !o.dataDir) {
+        throw new YskError(ErrorCodes.CONFIG_INVALID, tl('notes.auto.n1373'), { httpStatus: 400 });
+    }
+    return {
+        version: typeof o.version === 'number' ? o.version : 1,
+        product: 'ysk-server',
+        dataDir: o.dataDir,
+        listenHost: typeof o.listenHost === 'string' ? o.listenHost : DEFAULTS.listenHost,
+        listenPort: typeof o.listenPort === 'number' ? o.listenPort : DEFAULTS.listenPort,
+        adminUsername: typeof o.adminUsername === 'string' ? o.adminUsername : DEFAULTS.adminUsername,
+        locale: typeof o.locale === 'string' ? o.locale : DEFAULTS.locale,
+        setupCompleted: Boolean(o.setupCompleted),
+        createdAt: typeof o.createdAt === 'string' ? o.createdAt : new Date().toISOString(),
+        tlsEnabled: Boolean(o.tlsEnabled),
+        tlsCertPath: typeof o.tlsCertPath === 'string' ? o.tlsCertPath : undefined,
+        tlsKeyPath: typeof o.tlsKeyPath === 'string' ? o.tlsKeyPath : undefined,
+        panelDomain: typeof o.panelDomain === 'string' ? o.panelDomain : undefined,
+        httpListenPort: typeof o.httpListenPort === 'number' &&
+            Number.isInteger(o.httpListenPort) &&
+            o.httpListenPort > 0 &&
+            o.httpListenPort < 65536
+            ? o.httpListenPort
+            : undefined,
+        tlsHttpRedirect: o.tlsHttpRedirect === undefined ? true : Boolean(o.tlsHttpRedirect),
+        tlsHttpsOnly: Boolean(o.tlsHttpsOnly),
+    };
+}
+/** Default companion HTTP port when TLS is on (avoid privileged 80). */
+export function defaultHttpListenPort(httpsPort) {
+    if (httpsPort > 1024)
+        return httpsPort - 1;
+    return 9286;
+}
+/** Merge TLS / panel fields into existing config (persist-safe). */
+export function mergePanelTlsConfig(base, patch) {
+    const next = { ...base };
+    if (patch.tlsEnabled !== undefined)
+        next.tlsEnabled = patch.tlsEnabled;
+    if (patch.tlsCertPath !== undefined) {
+        next.tlsCertPath = patch.tlsCertPath || undefined;
+    }
+    if (patch.tlsKeyPath !== undefined) {
+        next.tlsKeyPath = patch.tlsKeyPath || undefined;
+    }
+    if (patch.panelDomain !== undefined) {
+        next.panelDomain = patch.panelDomain?.trim() || undefined;
+    }
+    if (patch.tlsHttpsOnly !== undefined)
+        next.tlsHttpsOnly = patch.tlsHttpsOnly;
+    if (patch.listenHost !== undefined && patch.listenHost.trim()) {
+        next.listenHost = patch.listenHost.trim();
+    }
+    // HTTPS-only: drop companion HTTP port so dual bind is skipped
+    if (next.tlsHttpsOnly) {
+        next.httpListenPort = undefined;
+    }
+    return next;
+}
+//# sourceMappingURL=schema.js.map

package/dist/config/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}

package/dist/db/database.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Open durable control-plane database.
+ *
+ * Backends (D4):
+ * - json (default): atomic ysk.json
+ * - sqlite: better-sqlite3 document blob (YSK_STORE=sqlite or path ends .sqlite)
+ * - postgres: optional pg + YSK_DATABASE_URL
+ *
+ * All backends are JsonStore (or subclass) — same snapshot API.
+ */
+import type { YskDatabase } from './store.js';
+import { type OpenStoreOptions, type StoreBackendKind } from './document-store.js';
+export type { StoreBackendKind, OpenStoreOptions };
+/**
+ * Open (or create) the control-plane database.
+ * Env: YSK_STORE=json|sqlite|postgres · YSK_DATABASE_URL for postgres.
+ */
+export declare function openDatabase(dbPath: string, opts?: OpenStoreOptions): YskDatabase;
+/** Async alias (same as sync for document backends). */
+export declare function openDatabaseAsync(dbPath: string, opts?: OpenStoreOptions): Promise<YskDatabase>;
+export declare function migrate(_db: YskDatabase): void;
+export declare function closeDatabase(db: YskDatabase): void;
+export type { YskDatabase };
+//# sourceMappingURL=database.d.ts.map

package/dist/db/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAEnD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAGjF;AAED,wDAAwD;AACxD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,WAAW,CAAC,CAGtB;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAE9C;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAEnD;AAED,YAAY,EAAE,WAAW,EAAE,CAAC"}

package/dist/db/database.js

@@ -0,0 +1,31 @@
+/**
+ * Open durable control-plane database.
+ *
+ * Backends (D4):
+ * - json (default): atomic ysk.json
+ * - sqlite: better-sqlite3 document blob (YSK_STORE=sqlite or path ends .sqlite)
+ * - postgres: optional pg + YSK_DATABASE_URL
+ *
+ * All backends are JsonStore (or subclass) — same snapshot API.
+ */
+import { openDocumentStoreSync, openDocumentStore, } from './document-store.js';
+/**
+ * Open (or create) the control-plane database.
+ * Env: YSK_STORE=json|sqlite|postgres · YSK_DATABASE_URL for postgres.
+ */
+export function openDatabase(dbPath, opts) {
+    const path = opts?.path ?? dbPath;
+    return openDocumentStoreSync({ ...opts, path });
+}
+/** Async alias (same as sync for document backends). */
+export async function openDatabaseAsync(dbPath, opts) {
+    const path = opts?.path ?? dbPath;
+    return openDocumentStore({ ...opts, path });
+}
+export function migrate(_db) {
+    // Document backends need no SQL migrations; schema.ts reserved for relational mode
+}
+export function closeDatabase(db) {
+    db.close();
+}
+//# sourceMappingURL=database.js.map

package/dist/db/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAGlB,MAAM,qBAAqB,CAAC;AAI7B;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,IAAuB;IAClE,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC;IAClC,OAAO,qBAAqB,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,IAAuB;IAEvB,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC;IAClC,OAAO,iBAAiB,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAgB;IACtC,mFAAmF;AACrF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAe;IAC3C,EAAE,CAAC,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/db/document-store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Document-store backends for control-plane state (D4).
+ *
+ * All backends subclass JsonStore so product code keeps db.snapshot + persist.
+ *
+ * - json     → atomic ysk.json (default)
+ * - sqlite   → sql.js via child process (pure JS, no native segfault risk)
+ * - postgres → optional `pg` via child process (experimental)
+ *
+ * Full relational schema remains in schema.ts for a future phase.
+ */
+import { JsonStore, type YskDatabase } from './store.js';
+export type StoreBackendKind = 'json' | 'sqlite' | 'postgres';
+export type OpenStoreOptions = {
+    kind?: StoreBackendKind;
+    path?: string;
+    url?: string;
+};
+export declare function resolveStoreBackend(opts?: OpenStoreOptions): {
+    kind: StoreBackendKind;
+    path?: string;
+    url?: string;
+};
+/** JsonStore dual-write to SQLite file via sql.js (child process). */
+export declare class ShellSqliteJsonStore extends JsonStore {
+    readonly backendKind: StoreBackendKind;
+    /**
+     * Set after super() — JsonStore ctor may call persist() before subclass fields init.
+     * Guard dual-write until ready, then persist again from openSqliteDocumentStore.
+     */
+    private _sqlitePath;
+    get sqlitePath(): string;
+    constructor(sqlitePath: string, mirrorJsonPath: string);
+    persist(): void;
+}
+/** JsonStore dual-write to Postgres (experimental). */
+export declare class PostgresJsonStore extends JsonStore {
+    readonly backendKind: StoreBackendKind;
+    private _connectionUrl;
+    get connectionUrl(): string;
+    constructor(url: string, mirrorJsonPath: string);
+    persist(): void;
+}
+export declare function openSqliteDocumentStore(sqlitePath: string): ShellSqliteJsonStore;
+export declare function openPostgresDocumentStore(url: string): PostgresJsonStore;
+export declare function openDocumentStoreSync(opts: OpenStoreOptions): JsonStore;
+export declare function openDocumentStore(opts: OpenStoreOptions): Promise<JsonStore>;
+export declare function exportStoreDocument(db: YskDatabase, outPath: string): {
+    ok: true;
+    path: string;
+    bytes: number;
+};
+export declare function importStoreDocument(db: YskDatabase, inPath: string): {
+    ok: true;
+    users: number;
+    projects: number;
+};
+export declare function storeStatus(db: YskDatabase, locationHint?: string): {
+    ok: true;
+    kind: StoreBackendKind;
+    location: string;
+    users: number;
+    projects: number;
+    notes: string[];
+};
+//# sourceMappingURL=document-store.d.ts.map

package/dist/db/document-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-store.d.ts","sourceRoot":"","sources":["../../src/db/document-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EAAE,SAAS,EAAkB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE9D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAIF,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,gBAAqB,GAAG;IAChE,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAmBA;AA2BD,sEAAsE;AACtE,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAY;IAClD;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAqB;IAExC,IAAI,UAAU,IAAI,MAAM,CAEvB;gBAEW,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;IAK7C,OAAO,IAAI,IAAI;CAkEzB;AAED,uDAAuD;AACvD,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAc;IACpD,OAAO,CAAC,cAAc,CAAqB;IAE3C,IAAI,aAAa,IAAI,MAAM,CAE1B;gBAEW,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;IAKtC,OAAO,IAAI,IAAI;CA4CzB;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,CAkDhF;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyCxE;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAkBvE;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAElF;AAED,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAO3C;AAED,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAkB/C;AAED,wBAAgB,WAAW,CACzB,EAAE,EAAE,WAAW,EACf,YAAY,CAAC,EAAE,MAAM,GACpB;IACD,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAyBA"}