jishushell 0.6.5 → 0.6.18

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

@@ -1,264 +0,0 @@
-/**
- * Encode an absolute filesystem path for use inside backup archives.
- * Ported from OpenClaw official: encodeAbsolutePathForBackupArchive.
- */
-export declare function encodeAbsolutePathForArchive(sourcePath: string): string;
-/**
- * Decode a path produced by {@link encodeAbsolutePathForArchive} back to
- * the original absolute filesystem path.
- *
- * - `"posix/Users/arm/foo"` → `"/Users/arm/foo"`
- * - `"windows/C/Users/foo"` → `"C:\\Users\\foo"`
- * - `"relative/some/path"`  → `"some/path"`
- *
- * Returns the input unchanged when the prefix is unrecognised.
- */
-export declare function decodeArchivePath(encodedPath: 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 config copy 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 {};