@serve.zone/gitops 2.13.1

package/ts/storage/classes.storagemanager.ts

@@ -0,0 +1,144 @@
+import * as plugins from '../plugins.js';
+
+export type TStorageBackend = 'filesystem' | 'memory';
+
+export interface IStorageConfig {
+  backend?: TStorageBackend;
+  fsPath?: string;
+}
+
+const isNotFoundError = (error: unknown): boolean => {
+  return error instanceof Error && (error as NodeJS.ErrnoException).code === 'ENOENT';
+};
+
+/**
+ * Key-value storage abstraction with filesystem and memory backends.
+ * Keys must start with '/' and are normalized (no '..', no double slashes).
+ */
+export class StorageManager {
+  private backend: TStorageBackend;
+  private fsPath: string;
+  private memoryStore: Map<string, string>;
+
+  constructor(config: IStorageConfig = {}) {
+    this.backend = config.backend ?? 'filesystem';
+    this.fsPath = config.fsPath ?? './storage';
+    this.memoryStore = new Map();
+  }
+
+  /**
+   * Normalize and validate a storage key.
+   */
+  private normalizeKey(key: string): string {
+    if (!key.startsWith('/')) {
+      throw new Error(`Storage key must start with '/': ${key}`);
+    }
+    // Strip '..' segments and normalize double slashes
+    const segments = key.split('/').filter((s) => s !== '' && s !== '..');
+    return '/' + segments.join('/');
+  }
+
+  /**
+   * Resolve a key to a filesystem path.
+   */
+  private keyToPath(key: string): string {
+    const normalized = this.normalizeKey(key);
+    return plugins.path.join(this.fsPath, ...normalized.split('/').filter(Boolean));
+  }
+
+  async get(key: string): Promise<string | null> {
+    const normalized = this.normalizeKey(key);
+    if (this.backend === 'memory') {
+      return this.memoryStore.get(normalized) ?? null;
+    }
+    try {
+      return await plugins.fs.readFile(this.keyToPath(normalized), 'utf8');
+    } catch (err) {
+      if (isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const normalized = this.normalizeKey(key);
+    if (this.backend === 'memory') {
+      this.memoryStore.set(normalized, value);
+      return;
+    }
+    const filePath = this.keyToPath(normalized);
+    const dir = plugins.path.dirname(filePath);
+    await plugins.fs.mkdir(dir, { recursive: true });
+    // Atomic write: write to temp then rename
+    const tmpPath = filePath + '.tmp';
+    await plugins.fs.writeFile(tmpPath, value, 'utf8');
+    await plugins.fs.rename(tmpPath, filePath);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const normalized = this.normalizeKey(key);
+    if (this.backend === 'memory') {
+      return this.memoryStore.delete(normalized);
+    }
+    try {
+      await plugins.fs.rm(this.keyToPath(normalized));
+      return true;
+    } catch (err) {
+      if (isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const normalized = this.normalizeKey(key);
+    if (this.backend === 'memory') {
+      return this.memoryStore.has(normalized);
+    }
+    try {
+      await plugins.fs.stat(this.keyToPath(normalized));
+      return true;
+    } catch (err) {
+      if (isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+
+  /**
+   * List keys under a given prefix.
+   */
+  async list(prefix: string): Promise<string[]> {
+    const normalized = this.normalizeKey(prefix);
+    if (this.backend === 'memory') {
+      const keys: string[] = [];
+      for (const key of this.memoryStore.keys()) {
+        if (key.startsWith(normalized)) {
+          keys.push(key);
+        }
+      }
+      return keys.sort();
+    }
+    const dirPath = this.keyToPath(normalized);
+    const keys: string[] = [];
+    try {
+      const entries = await plugins.fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile()) {
+          keys.push(normalized.replace(/\/$/, '') + '/' + entry.name);
+        }
+      }
+    } catch (err) {
+      if (isNotFoundError(err)) return [];
+      throw err;
+    }
+    return keys.sort();
+  }
+
+  async getJSON<T>(key: string): Promise<T | null> {
+    const raw = await this.get(key);
+    if (raw === null) return null;
+    return JSON.parse(raw) as T;
+  }
+
+  async setJSON(key: string, value: unknown): Promise<void> {
+    await this.set(key, JSON.stringify(value, null, 2));
+  }
+}

package/ts/storage/index.ts

@@ -0,0 +1,2 @@
+export { StorageManager } from './classes.storagemanager.js';
+export type { IStorageConfig, TStorageBackend } from './classes.storagemanager.js';

package/ts/timers.ts

@@ -0,0 +1,34 @@
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MS_PER_MINUTE = 60_000;
+
+export const MAX_INTERVAL_MINUTES = Math.floor(MAX_TIMER_DELAY_MS / MS_PER_MINUTE);
+
+export const validateIntervalMinutes = (
+  value: number | undefined,
+  label = 'intervalMinutes',
+  fallback?: number,
+): number => {
+  const intervalMinutes = value ?? fallback;
+  if (
+    intervalMinutes === undefined ||
+    !Number.isFinite(intervalMinutes) ||
+    !Number.isInteger(intervalMinutes) ||
+    intervalMinutes < 1 ||
+    intervalMinutes > MAX_INTERVAL_MINUTES
+  ) {
+    throw new Error(`${label} must be an integer between 1 and ${MAX_INTERVAL_MINUTES}`);
+  }
+
+  return intervalMinutes;
+};
+
+export const intervalMinutesToMs = (value: number, label = 'intervalMinutes'): number => {
+  return validateIntervalMinutes(value, label) * MS_PER_MINUTE;
+};
+
+export const unrefTimer = (timer: ReturnType<typeof setInterval> | ReturnType<typeof setTimeout>): void => {
+  const unref = (timer as { unref?: () => void }).unref;
+  if (typeof unref === 'function') {
+    unref.call(timer);
+  }
+};

package/ts_interfaces/data/actionlog.ts

@@ -0,0 +1,13 @@
+export type TActionType = 'create' | 'update' | 'delete' | 'pause' | 'resume' | 'test' | 'scan' | 'sync' | 'obsolete' | 'push' | 'run';
+export type TActionEntity = 'connection' | 'secret' | 'pipeline' | 'sync' | 'managed-secret' | 'job';
+
+export interface IActionLogEntry {
+  id: string;
+  timestamp: number;
+  actionType: TActionType;
+  entityType: TActionEntity;
+  entityId: string;
+  entityName: string;
+  details: string;
+  username: string;
+}

package/ts_interfaces/data/branch.ts

@@ -0,0 +1,9 @@
+export interface IBranch {
+  name: string;
+  commitSha: string;
+}
+
+export interface ITag {
+  name: string;
+  commitSha: string;
+}

package/ts_interfaces/data/connection.ts

@@ -0,0 +1,13 @@
+export type TProviderType = 'gitea' | 'gitlab';
+
+export interface IProviderConnection {
+  id: string;
+  name: string;
+  providerType: TProviderType;
+  baseUrl: string;
+  token: string;
+  createdAt: number;
+  status: 'connected' | 'disconnected' | 'error' | 'paused';
+  groupFilter?: string;      // Restricts which repos this connection can see (e.g. "foss.global")
+  groupFilterId?: string;    // Resolved filter group ID (numeric for GitLab, org name for Gitea)
+}

package/ts_interfaces/data/group.ts

@@ -0,0 +1,10 @@
+export interface IGroup {
+  id: string;
+  name: string;
+  fullPath: string;
+  description: string;
+  webUrl: string;
+  connectionId: string;
+  visibility: string;
+  projectCount: number;
+}

package/ts_interfaces/data/identity.ts

@@ -0,0 +1,7 @@
+export interface IIdentity {
+  jwt: string;
+  userId: string;
+  username: string;
+  expiresAt: number;
+  role: 'admin' | 'user';
+}

package/ts_interfaces/data/index.ts

@@ -0,0 +1,11 @@
+export * from './identity.js';
+export * from './connection.js';
+export * from './project.js';
+export * from './group.js';
+export * from './branch.js';
+export * from './secret.js';
+export * from './pipeline.js';
+export * from './actionlog.js';
+export * from './sync.js';
+export * from './managedsecret.js';
+export * from './job.js';

package/ts_interfaces/data/job.ts

@@ -0,0 +1,42 @@
+export type TJobType = 'autobookstackdocs';
+
+export type TJobStatus = 'active' | 'paused' | 'error';
+
+export interface IBookstackTarget {
+  baseUrl: string;
+  tokenId: string;
+  tokenSecret: string; // "keychain:<id>" sentinel in storage, real value in memory
+}
+
+export interface IAutoBookstackDocsConfig {
+  sourceConnectionIds: string[];
+  bookstackTarget: IBookstackTarget;
+  filePaths: string[];              // root-level files to sync, e.g. ["readme.md"]
+  docDirs: string[];                // directories to scan for .md files, e.g. ["docs"]
+  includeGroups?: string[];
+  excludeGroups?: string[];
+  propagateDeletes?: boolean;       // remove stale shelves/books/pages (default false)
+  syncVisibility?: boolean;         // map git visibility to BookStack permissions (default false)
+  privateRoleId?: number;           // BookStack role ID for private content access
+}
+
+export interface IJobLogEntry {
+  timestamp: number;
+  level: 'info' | 'warn' | 'error' | 'success' | 'debug';
+  message: string;
+  source?: string;
+}
+
+export interface IJobConfig {
+  id: string;
+  name: string;
+  jobType: TJobType;
+  status: TJobStatus;
+  intervalMinutes: number;
+  lastRunAt: number;
+  lastRunDurationMs?: number;
+  lastRunError?: string;
+  createdAt: number;
+  updatedAt: number;
+  autoBookstackDocsConfig?: IAutoBookstackDocsConfig;
+}

package/ts_interfaces/data/managedsecret.ts

@@ -0,0 +1,41 @@
+export interface IManagedSecretTarget {
+  connectionId: string;
+  scope: 'project' | 'group';
+  scopeId: string;
+  scopeName: string;
+}
+
+export type TPushStatus = 'pending' | 'success' | 'error';
+
+export interface IManagedSecretTargetStatus {
+  connectionId: string;
+  scope: 'project' | 'group';
+  scopeId: string;
+  scopeName: string;
+  status: TPushStatus;
+  error?: string;
+  lastPushedAt?: number;
+}
+
+export interface IManagedSecret {
+  id: string;
+  key: string;
+  description?: string;
+  targets: IManagedSecretTarget[];
+  targetStatuses: IManagedSecretTargetStatus[];
+  createdAt: number;
+  updatedAt: number;
+  lastPushedAt?: number;
+}
+
+export interface IManagedSecretStored {
+  id: string;
+  key: string;
+  description?: string;
+  value: string;
+  targets: IManagedSecretTarget[];
+  targetStatuses: IManagedSecretTargetStatus[];
+  createdAt: number;
+  updatedAt: number;
+  lastPushedAt?: number;
+}

package/ts_interfaces/data/pipeline.ts

@@ -0,0 +1,32 @@
+export type TPipelineStatus =
+  | 'pending'
+  | 'running'
+  | 'success'
+  | 'failed'
+  | 'canceled'
+  | 'skipped'
+  | 'waiting'
+  | 'manual';
+
+export interface IPipeline {
+  id: string;
+  projectId: string;
+  projectName: string;
+  connectionId: string;
+  status: TPipelineStatus;
+  ref: string;
+  sha: string;
+  webUrl: string;
+  duration: number;
+  createdAt: string;
+  source: string;
+}
+
+export interface IPipelineJob {
+  id: string;
+  pipelineId: string;
+  name: string;
+  stage: string;
+  status: TPipelineStatus;
+  duration: number;
+}

package/ts_interfaces/data/project.ts

@@ -0,0 +1,12 @@
+export interface IProject {
+  id: string;
+  name: string;
+  fullPath: string;
+  description: string;
+  defaultBranch: string;
+  webUrl: string;
+  connectionId: string;
+  visibility: string;
+  topics: string[];
+  lastActivity: string;
+}

package/ts_interfaces/data/secret.ts

@@ -0,0 +1,11 @@
+export interface ISecret {
+  key: string;
+  value: string;
+  protected: boolean;
+  masked: boolean;
+  scope: 'project' | 'group';
+  scopeId: string;
+  scopeName: string;
+  connectionId: string;
+  environment: string;
+}

package/ts_interfaces/data/sync.ts

@@ -0,0 +1,37 @@
+export type TSyncStatus = 'active' | 'paused' | 'error';
+
+export interface ISyncConfig {
+  id: string;
+  name: string;
+  sourceConnectionId: string;
+  targetConnectionId: string;
+  targetGroupOffset?: string;    // Path prefix for target repos (e.g. "mirror/gitlab")
+  intervalMinutes: number;      // Default 5
+  status: TSyncStatus;
+  lastSyncAt: number;
+  lastSyncError?: string;
+  lastSyncDurationMs?: number;
+  reposSynced: number;
+  enforceDelete: boolean;         // When true, stale target repos are moved to obsolete
+  enforceGroupDelete: boolean;    // When true, stale target groups/orgs are moved to obsolete
+  addMirrorHint?: boolean;        // When true, target descriptions get "(This is a mirror of ...)" appended
+  useGroupAvatarsForProjects?: boolean; // When true, projects without avatars inherit the group avatar
+  createdAt: number;
+}
+
+export interface ISyncRepoStatus {
+  id: string;
+  syncConfigId: string;
+  sourceFullPath: string;       // e.g. "push.rocks/smartstate"
+  targetFullPath: string;       // e.g. "foss.global/push.rocks/smartstate"
+  lastSyncAt: number;
+  lastSyncError?: string;
+  status: 'synced' | 'error' | 'pending';
+}
+
+export interface ISyncLogEntry {
+  timestamp: number;
+  level: 'info' | 'warn' | 'error' | 'success' | 'debug';
+  message: string;
+  source?: string;   // e.g. 'preview', 'sync', 'git', 'api'
+}

package/ts_interfaces/index.ts

@@ -0,0 +1,9 @@
+export * from './plugins.js';
+
+// Data types
+import * as data from './data/index.js';
+export { data };
+
+// Request interfaces
+import * as requests from './requests/index.js';
+export { requests };

package/ts_interfaces/plugins.ts

@@ -0,0 +1,6 @@
+// @apiglobal scope
+import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+
+export {
+  typedrequestInterfaces,
+};

package/ts_interfaces/requests/actionlog.ts

@@ -0,0 +1,19 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_GetActionLog extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetActionLog
+> {
+  method: 'getActionLog';
+  request: {
+    identity: data.IIdentity;
+    limit?: number;
+    offset?: number;
+    entityType?: data.TActionEntity;
+  };
+  response: {
+    entries: data.IActionLogEntry[];
+    total: number;
+  };
+}

package/ts_interfaces/requests/actions.ts

@@ -0,0 +1,39 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ForceScanSecrets extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ForceScanSecrets
+> {
+  method: 'forceScanSecrets';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    ok: boolean;
+    connectionsScanned: number;
+    secretsFound: number;
+    errors: string[];
+    durationMs: number;
+  };
+}
+
+export interface IReq_GetScanStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetScanStatus
+> {
+  method: 'getScanStatus';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    lastScanTimestamp: number;
+    isScanning: boolean;
+    lastResult: {
+      connectionsScanned: number;
+      secretsFound: number;
+      errors: string[];
+      durationMs: number;
+    } | null;
+  };
+}

package/ts_interfaces/requests/admin.ts

@@ -0,0 +1,43 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_AdminLogin extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_AdminLogin
+> {
+  method: 'adminLogin';
+  request: {
+    username: string;
+    password: string;
+  };
+  response: {
+    identity?: data.IIdentity;
+  };
+}
+
+export interface IReq_AdminLogout extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_AdminLogout
+> {
+  method: 'adminLogout';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    ok: boolean;
+  };
+}
+
+export interface IReq_VerifyIdentity extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_VerifyIdentity
+> {
+  method: 'verifyIdentity';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    valid: boolean;
+    identity?: data.IIdentity;
+  };
+}

package/ts_interfaces/requests/connections.ts

@@ -0,0 +1,95 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_GetConnections extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetConnections
+> {
+  method: 'getConnections';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    connections: data.IProviderConnection[];
+  };
+}
+
+export interface IReq_CreateConnection extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateConnection
+> {
+  method: 'createConnection';
+  request: {
+    identity: data.IIdentity;
+    name: string;
+    providerType: data.TProviderType;
+    baseUrl: string;
+    token: string;
+    groupFilter?: string;
+  };
+  response: {
+    connection: data.IProviderConnection;
+  };
+}
+
+export interface IReq_UpdateConnection extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_UpdateConnection
+> {
+  method: 'updateConnection';
+  request: {
+    identity: data.IIdentity;
+    connectionId: string;
+    name?: string;
+    baseUrl?: string;
+    token?: string;
+    groupFilter?: string;
+  };
+  response: {
+    connection: data.IProviderConnection;
+  };
+}
+
+export interface IReq_TestConnection extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_TestConnection
+> {
+  method: 'testConnection';
+  request: {
+    identity: data.IIdentity;
+    connectionId: string;
+  };
+  response: {
+    ok: boolean;
+    error?: string;
+  };
+}
+
+export interface IReq_PauseConnection extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PauseConnection
+> {
+  method: 'pauseConnection';
+  request: {
+    identity: data.IIdentity;
+    connectionId: string;
+    paused: boolean;
+  };
+  response: {
+    connection: data.IProviderConnection;
+  };
+}
+
+export interface IReq_DeleteConnection extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_DeleteConnection
+> {
+  method: 'deleteConnection';
+  request: {
+    identity: data.IIdentity;
+    connectionId: string;
+  };
+  response: {
+    ok: boolean;
+  };
+}

package/ts_interfaces/requests/groups.ts

@@ -0,0 +1,18 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_GetGroups extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGroups
+> {
+  method: 'getGroups';
+  request: {
+    identity: data.IIdentity;
+    connectionId: string;
+    search?: string;
+    page?: number;
+  };
+  response: {
+    groups: data.IGroup[];
+  };
+}

package/ts_interfaces/requests/index.ts

@@ -0,0 +1,13 @@
+export * from './admin.js';
+export * from './connections.js';
+export * from './projects.js';
+export * from './groups.js';
+export * from './secrets.js';
+export * from './pipelines.js';
+export * from './logs.js';
+export * from './webhook.js';
+export * from './actions.js';
+export * from './actionlog.js';
+export * from './sync.js';
+export * from './managedsecrets.js';
+export * from './jobs.js';