feat(session-backups): store snapshots in private repo

Author: skulidropek

.githooks/pre-push

@@ -11,13 +11,13 @@ fi
 
 node scripts/pre-push-knowledge-guard.js "$@"
 
-# CHANGE: backup AI session to private gist on push (supports Claude, Codex, Gemini)
-# WHY: allows returning to old AI sessions and provides PR context
+# CHANGE: backup AI session to a private session repository on push (supports Claude, Codex, Gemini)
+# WHY: allows returning to old AI sessions and provides PR context without gist limits
 # QUOTE(ТЗ): "когда происходит push мы сразу заливаем текущую сессию с AI агентом в gits приватный"
 # REF: issue-143
 # PURITY: SHELL
 if [ "${DOCKER_GIT_SKIP_SESSION_BACKUP:-}" != "1" ]; then
-  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+  if command -v gh >/dev/null 2>&1; then
     node scripts/session-backup-gist.js --verbose || echo "[session-backup] Warning: session backup failed (non-fatal)"
   fi
 fi

packages/app/src/docker-git/cli/parser-session-gists.ts

@@ -11,8 +11,8 @@ import {
 
 import { parsePositiveInt, parseProjectDirWithOptions, splitSubcommand } from "./parser-shared.js"
 
-// CHANGE: parse session gist commands for backup/list/view/download
-// WHY: enables CLI access to session backup gist functionality
+// CHANGE: parse session backup commands for backup/list/view/download
+// WHY: enables CLI access to session backup repository functionality
 // QUOTE(ТЗ): "иметь возможность возвращаться ко всем старым сессиям с агентами"
 // REF: issue-143
 // PURITY: CORE
@@ -23,11 +23,11 @@ import { parsePositiveInt, parseProjectDirWithOptions, splitSubcommand } from ".
 const defaultLimit = 20
 const defaultOutputDir = "./.session-restore"
 
-const missingGistIdError: ParseError = { _tag: "MissingRequiredOption", option: "gist-id" }
+const missingSnapshotRefError: ParseError = { _tag: "MissingRequiredOption", option: "snapshot-ref" }
 
-const extractGistId = (args: ReadonlyArray<string>): string | null => {
-  const gistId = args[0]
-  return gistId && !gistId.startsWith("-") ? gistId : null
+const extractSnapshotRef = (args: ReadonlyArray<string>): string | null => {
+  const snapshotRef = args[0]
+  return snapshotRef && !snapshotRef.startsWith("-") ? snapshotRef : null
 }
 
 const parseBackup = (
@@ -59,22 +59,22 @@ const parseList = (
 const parseView = (
   args: ReadonlyArray<string>
 ): Either.Either<SessionGistViewCommand, ParseError> => {
-  const gistId = extractGistId(args)
-  return gistId
-    ? Either.right({ _tag: "SessionGistView", gistId })
-    : Either.left(missingGistIdError)
+  const snapshotRef = extractSnapshotRef(args)
+  return snapshotRef
+    ? Either.right({ _tag: "SessionGistView", snapshotRef })
+    : Either.left(missingSnapshotRefError)
 }
 
 const parseDownload = (
   args: ReadonlyArray<string>
 ): Either.Either<SessionGistDownloadCommand, ParseError> => {
-  const gistId = extractGistId(args)
-  if (!gistId) {
-    return Either.left(missingGistIdError)
+  const snapshotRef = extractSnapshotRef(args)
+  if (!snapshotRef) {
+    return Either.left(missingSnapshotRefError)
   }
   return Either.map(parseProjectDirWithOptions(args.slice(1)), ({ raw }) => ({
     _tag: "SessionGistDownload",
-    gistId,
+    snapshotRef,
     outputDir: raw.output ?? defaultOutputDir
   }))
 }

packages/app/src/docker-git/cli/usage.ts

@@ -16,8 +16,8 @@ docker-git sessions kill <pid> [<url>] [options]
 docker-git sessions logs <pid> [<url>] [options]
 docker-git session-gists [list] [options]
 docker-git session-gists backup [<url>] [options]
-docker-git session-gists view <gist-id>
-docker-git session-gists download <gist-id> [options]
+docker-git session-gists view <snapshot-ref>
+docker-git session-gists download <snapshot-ref> [options]
 docker-git ps
 docker-git down-all
 docker-git auth <provider> <action> [options]
@@ -34,7 +34,7 @@ Commands:
   panes, terms        List tmux panes for a docker-git project
   scrap               Export/import project scrap (session snapshot + rebuildable deps)
   sessions            List/kill/log container terminal processes
-  session-gists       Manage AI session backups via GitHub Gists (backup/list/view/download)
+  session-gists       Manage AI session backups via a private session repository (backup/list/view/download)
   ps, status          Show docker compose status for all docker-git projects
   down-all            Stop all docker-git containers (docker compose down)
   auth                Manage GitHub/Codex/Claude Code auth for docker-git
@@ -71,8 +71,8 @@ Options:
   --include-default         Show default/system processes in sessions list
   --pr-number <n>           PR number for session backup comment
   --repo <owner/repo>       Repository for session backup operations
-  --limit <n>               Limit for session-gists list (default: 20)
-  --output <path>           Output directory for session-gists download (default: ./.session-restore)
+  --limit <n>               Limit for session backup snapshot list (default: 20)
+  --output <path>           Output directory for session backup download (default: ./.session-restore)
   --no-comment              Skip posting PR comment after session backup
   --up | --no-up            Run docker compose up after init (default: --up)
   --ssh | --no-ssh          Auto-open SSH after create/clone (default: clone=--ssh, create=--no-ssh)

packages/lib/src/core/session-gist-domain.ts

@@ -1,5 +1,5 @@
-// CHANGE: session gist backup commands for PR-based session history
-// WHY: enables returning to old AI sessions via private gists linked to PRs
+// CHANGE: session backup commands for PR-based session history
+// WHY: enables returning to old AI sessions via a private backup repository
 // QUOTE(ТЗ): "иметь возможность возвращаться ко всем старым сессиям с агентами"
 // REF: issue-143
 // PURITY: CORE
@@ -20,12 +20,12 @@ export interface SessionGistListCommand {
 
 export interface SessionGistViewCommand {
   readonly _tag: "SessionGistView"
-  readonly gistId: string
+  readonly snapshotRef: string
 }
 
 export interface SessionGistDownloadCommand {
   readonly _tag: "SessionGistDownload"
-  readonly gistId: string
+  readonly snapshotRef: string
   readonly outputDir: string
 }
 

packages/lib/src/core/templates-entrypoint/git.ts

@@ -262,7 +262,7 @@ REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 cd "$REPO_ROOT"
 
 if [ "${"${"}DOCKER_GIT_SKIP_SESSION_BACKUP:-}" != "1" ]; then
-  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+  if command -v gh >/dev/null 2>&1; then
     node scripts/session-backup-gist.js --verbose || echo "[session-backup] Warning: session backup failed (non-fatal)"
   fi
 fi

packages/lib/src/usecases/session-gists.ts

@@ -11,7 +11,7 @@ import type {
 import { runCommandWithExitCodes } from "../shell/command-runner.js"
 import { CommandFailedError } from "../shell/errors.js"
 
-// CHANGE: implement session gist operations via shell commands
+// CHANGE: implement session backup repository operations via shell commands
 // WHY: enables CLI access to session backup/list/view/download functionality
 // QUOTE(ТЗ): "иметь возможность возвращаться ко всем старым сессиям с агентами"
 // REF: issue-143
@@ -55,7 +55,7 @@ export const sessionGistBackup = (
     args.push("--no-comment")
   }
   return Effect.gen(function*(_) {
-    yield* _(Effect.log("Backing up AI session to private gist..."))
+    yield* _(Effect.log("Backing up AI session to private session repository..."))
     yield* _(runNodeScript("scripts/session-backup-gist.js", args))
     yield* _(Effect.log("Session backup complete."))
   })
@@ -69,7 +69,7 @@ export const sessionGistList = (
     args.push("--repo", cmd.repo)
   }
   return Effect.gen(function*(_) {
-    yield* _(Effect.log("Listing session backup gists..."))
+    yield* _(Effect.log("Listing session backup snapshots..."))
     yield* _(runNodeScript("scripts/session-list-gists.js", args))
   })
 }
@@ -78,15 +78,15 @@ export const sessionGistView = (
   cmd: SessionGistViewCommand
 ): Effect.Effect<void, SessionGistsError, SessionGistsRequirements> =>
   Effect.gen(function*(_) {
-    yield* _(Effect.log(`Viewing gist: ${cmd.gistId}`))
-    yield* _(runNodeScript("scripts/session-list-gists.js", ["view", cmd.gistId]))
+    yield* _(Effect.log(`Viewing snapshot: ${cmd.snapshotRef}`))
+    yield* _(runNodeScript("scripts/session-list-gists.js", ["view", cmd.snapshotRef]))
   })
 
 export const sessionGistDownload = (
   cmd: SessionGistDownloadCommand
 ): Effect.Effect<void, SessionGistsError, SessionGistsRequirements> =>
   Effect.gen(function*(_) {
-    yield* _(Effect.log(`Downloading gist ${cmd.gistId} to ${cmd.outputDir}...`))
-    yield* _(runNodeScript("scripts/session-list-gists.js", ["download", cmd.gistId, "--output", cmd.outputDir]))
+    yield* _(Effect.log(`Downloading snapshot ${cmd.snapshotRef} to ${cmd.outputDir}...`))
+    yield* _(runNodeScript("scripts/session-list-gists.js", ["download", cmd.snapshotRef, "--output", cmd.outputDir]))
     yield* _(Effect.log("Download complete."))
   })