jishushell 0.4.2 → 0.4.10

package/dist/services/backup-manager.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Encode an absolute filesystem path for use inside backup archives.
+ * Ported from OpenClaw official: encodeAbsolutePathForBackupArchive.
+ */
+export declare function encodeAbsolutePathForArchive(sourcePath: string): string;
+export interface CallOpenclawBackupResult {
+    ok: boolean;
+    archivePath?: string;
+    error?: string;
+}
+/**
+ * Try to create a backup by calling the official `openclaw backup create` CLI.
+ * Returns ok:false if the binary is missing or the command fails.
+ */
+export declare function callOpenclawBackup(instanceId: string, outputDir: string, opts: {
+    onlyConfig?: boolean;
+    noWorkspace?: boolean;
+}): Promise<CallOpenclawBackupResult>;
+/** Ensure backup and tmp directories exist */
+export declare function ensureBackupDirs(): void;
+/**
+ * Get the per-instance export output directory (TMP_DIR/exports/<id>/).
+ * Exports live in an isolated subdirectory so the download route can enforce
+ * `:id` → file ownership and one instance's URL can't reach another's archive.
+ */
+export declare function getInstanceExportDir(instanceId: string): string;
+/** Clean up stale tmp files older than 30 minutes. Call on startup and periodically. */
+export declare function cleanupStaleTmpFiles(): number;
+/** Start periodic tmp cleanup. Call once at server startup. */
+export declare function startTmpCleanupScheduler(): void;
+/** Stop the cleanup scheduler (for graceful shutdown). */
+export declare function stopTmpCleanupScheduler(): void;
+/** Get the backup directory for an instance (creates if needed) */
+export declare function getInstanceBackupDir(instanceId: string): string;
+/** List all backup files for an instance, sorted by mtime descending (newest first) */
+export declare function listInstanceBackups(instanceId: string): Array<{
+    filename: string;
+    size: number;
+    created_at: string;
+    type: "auto-backup" | "manual-backup" | "pre-restore";
+}>;
+/** List all instance IDs that have backups (including orphans) */
+export declare function listAllBackupInstanceIds(): string[];
+/** Acquire an exclusive lock for an instance. Returns false if already locked. */
+export declare function acquireInstanceLock(instanceId: string, operation: string): boolean;
+/** Update heartbeat for a held lock. Call periodically during long operations. */
+export declare function touchInstanceLock(instanceId: string): void;
+/** Release the lock for an instance. */
+export declare function releaseInstanceLock(instanceId: string): void;
+/** Get current lock status for an instance (for status API). */
+export declare function getInstanceLockStatus(instanceId: string): {
+    locked: boolean;
+    operation?: string;
+} | null;
+/** Start a heartbeat interval for long operations. Returns a cleanup function. */
+export declare function startLockHeartbeat(instanceId: string, intervalMs?: number): () => void;
+/** Check if instance is locked. Throws with 409 status if locked. */
+export declare function assertNotLocked(instanceId: string): void;
+/** Detect whether system tar is GNU or BSD. Cached after first call. */
+export declare function detectTarVariant(): "gnu" | "bsd";
+interface TarEntry {
+    type: string;
+    size: number;
+    path: string;
+}
+/**
+ * Pre-scan a tar.gz archive for security threats.
+ * Throws on: path traversal, symlinks, hardlinks, absolute paths, oversized.
+ */
+export declare function preScanArchive(archivePath: string): {
+    entries: TarEntry[];
+    totalSize: number;
+};
+/**
+ * Safely extract a tar.gz archive to destDir.
+ * Pre-scans for security threats, then extracts with safety flags.
+ */
+export declare function safeExtract(archivePath: string, destDir: string): Promise<{
+    entries: TarEntry[];
+    totalSize: number;
+}>;
+export interface PackResult {
+    filename: string;
+    filepath: string;
+    size: number;
+    manifest: Record<string, any>;
+}
+/** Create a manual or auto backup of an instance */
+export declare function backupInstance(instanceId: string, opts?: {
+    includeSessions?: boolean;
+    includeWorkspace?: boolean;
+    onlyConfig?: boolean;
+    outputPath?: string;
+    type?: "manual-backup" | "auto-backup";
+    scope?: "state" | "home";
+}): Promise<PackResult>;
+export interface SelfPackOptions {
+    type: "manual-backup" | "auto-backup" | "pre-restore" | "export";
+    scope?: "state" | "home";
+    includeSessions?: boolean;
+    includeWorkspace?: boolean;
+    onlyConfig?: boolean;
+}
+/**
+ * Pack an instance in the official OpenClaw backup archive format.
+ * Layout: manifest.json at root + payload/<encoded-path>/.openclaw/...
+ * This is the fallback when `openclaw backup create` CLI is unavailable.
+ */
+export declare function selfPackOfficialFormat(instanceId: string, outputPath: string, opts: SelfPackOptions): Promise<PackResult>;
+export interface RestoreResult {
+    ok: boolean;
+    warnings: string[];
+    api_key_status: "preserved" | "lost" | "not_applicable";
+    rolled_back?: boolean;
+}
+/**
+ * Restore an instance from a backup file.
+ * Full flow: lock -> extract -> validate -> pre-restore backup -> stop -> restore -> rebuild -> start -> healthcheck -> rollback on failure
+ */
+export declare function restoreInstance(instanceId: string, backupFilePath: string): Promise<RestoreResult>;
+/**
+ * Create a new instance from a backup file.
+ * Does NOT copy model.env (new proxy token), provider.env (can't decrypt), or IM credentials.
+ * Hard rule: provider.env is always ignored — no decrypt attempt, no migration.
+ */
+export declare function createFromBackup(backupFilePath: string, opts: {
+    newId: string;
+    newName: string;
+    newDescription?: string;
+}): Promise<{
+    ok: boolean;
+    instance_id: string;
+    warnings: string[];
+}>;
+/**
+ * Export an instance for sharing. Uses WHITELIST strategy — only safe directories included.
+ * API keys and credentials are stripped. Sensitive fields in openclaw.json are scrubbed.
+ */
+export declare function exportInstance(instanceId: string, opts?: {
+    includeSessions?: boolean;
+    outputPath?: string;
+}): Promise<PackResult>;
+/** Step 1: Store uploaded file to tmp. Returns temp_id for subsequent calls. */
+export declare function storeUpload(filePath: string): Promise<{
+    temp_id: string;
+}>;
+/** Step 2: Preview an uploaded archive without creating an instance. */
+export declare function previewImport(tempId: string): Promise<{
+    manifest: Record<string, any> | null;
+    warnings: string[];
+    estimated_size: number;
+    format: "official" | "unknown";
+}>;
+/** Step 3: Create a new instance from a previously uploaded archive. */
+export declare function importInstance(tempId: string, opts: {
+    id: string;
+    name: string;
+    description?: string;
+}): Promise<{
+    ok: boolean;
+    instance_id: string;
+    warnings: string[];
+}>;
+/**
+ * Resolve the effective "archive root" inside an extracted tarball.
+ *
+ * Returns the directory where `manifest.json` and `payload/` live. Two
+ * archive layouts are supported:
+ *
+ *   1. **JishuShell self-pack** (`selfPackOfficialFormat`): writes
+ *      `manifest.json` and `payload/` directly at the archive root, so the
+ *      effective root is the extraction dir itself.
+ *
+ *   2. **Official OpenClaw `backup create`**: wraps everything inside a
+ *      single top-level directory named after the archive basename, e.g.
+ *      `2026-04-10T03-06-23.257Z-openclaw-backup/`. The wrapper name is
+ *      also advertised via `manifest.archiveRoot`.
+ *
+ * Detection strategy (cheapest first):
+ *   a. If `<tmpDir>/manifest.json` exists → self-pack → return tmpDir.
+ *   b. Else scan top-level entries; if exactly one is a directory containing
+ *      `manifest.json`, that's the official CLI wrapper → return it.
+ *   c. Fall back to tmpDir; the caller will throw its own missing-manifest
+ *      error with a meaningful path.
+ *
+ * Without this helper, `restoreInstance` / `importInstance` / `verifyArchive`
+ * would throw "Archive missing manifest.json" on every state-scope archive
+ * produced by the official CLI.
+ */
+export declare function resolveArchiveRoot(tmpDir: string): string;
+/**
+ * Locate the OpenClaw state directory inside an extracted archive.
+ *
+ * Finds a directory **literally named `.openclaw`** that contains an
+ * `openclaw.json` file. Uses BFS so the shallowest match wins, which guards
+ * against nested copies inside extensions/ or workspace/.
+ *
+ * This is intentionally stricter than "any directory containing
+ * openclaw.json". JishuShell's `saveConfig` double-writes the config to both
+ * `.openclaw/openclaw.json` and an outer legacy alias at
+ * `openclaw-home/openclaw.json`, so a naive "first dir with openclaw.json"
+ * search would incorrectly pick the `openclaw-home/` root for home-scope
+ * archives.
+ */
+export declare function findStateDir(rootDir: string): string | null;
+interface AutoBackupConfig {
+    enabled: boolean;
+    interval_hours: number;
+    keep_count: number;
+    last_backup_at?: string;
+    last_backup_ok?: boolean;
+    consecutive_failures?: number;
+    warnings?: string[];
+}
+/** Get auto-backup config from instance.json */
+export declare function getAutoBackupConfig(instanceId: string): Promise<AutoBackupConfig | null>;
+/** Clean old auto-backup files, keeping only the newest `keepCount` */
+export declare function cleanOldAutoBackups(instanceId: string, keepCount: number): Promise<number>;
+export interface BackupJob {
+    id: string;
+    instanceId: string;
+    operation: "manual-backup" | "auto-backup" | "export" | "restore" | "import" | "create-from-backup";
+    status: "queued" | "running" | "completed" | "failed";
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    progress?: string;
+    error?: string;
+    result?: any;
+}
+/** Enqueue a backup operation. Returns the job immediately (non-blocking). */
+export declare function enqueueJob(instanceId: string, operation: BackupJob["operation"], executeFn: (job: BackupJob) => Promise<any>): BackupJob;
+/** Enqueue and wait for completion. Returns the completed job. */
+export declare function enqueueJobAndWait(instanceId: string, operation: BackupJob["operation"], executeFn: (job: BackupJob) => Promise<any>): Promise<BackupJob>;
+/** Update progress message for the currently running job */
+export declare function updateJobProgress(jobId: string, progress: string): void;
+/** Get full queue status */
+export declare function getQueueStatus(): {
+    current: BackupJob | null;
+    queued: BackupJob[];
+    recent: BackupJob[];
+};
+/** Get a specific job by ID (checks current, queue, and history) */
+export declare function getJob(jobId: string): BackupJob | null;
+/** Cancel a queued job (cannot cancel running jobs) */
+export declare function cancelJob(jobId: string): boolean;
+/** Schedule auto-backup for an instance */
+export declare function scheduleAutoBackup(instanceId: string, config: AutoBackupConfig): void;
+/** Cancel auto-backup for an instance */
+export declare function cancelAutoBackup(instanceId: string): void;
+/** Initialize auto-backup for all instances (call on server startup) */
+export declare function initAutoBackup(): Promise<void>;
+export {};