fix: harden CLI and plugin edge cases

Author: Alan-TheGentleman

cmd/engram/cloud.go

@@ -133,6 +133,11 @@ func cmdCloud(cfg store.Config) {
 		fmt.Fprintln(os.Stderr, "supported subcommands: status, enroll, config, serve, upgrade")
 		exitFunc(1)
 	}
+	if os.Args[2] == "--help" || os.Args[2] == "-h" || os.Args[2] == "help" {
+		fmt.Println("usage: engram cloud <subcommand> [options]")
+		fmt.Println("supported subcommands: status, enroll, config, serve, upgrade")
+		return
+	}
 
 	switch os.Args[2] {
 	case "status":
@@ -559,6 +564,14 @@ func cmdCloudStatus(cfg store.Config) {
 }
 
 func cmdCloudEnroll(cfg store.Config) {
+	if len(os.Args) >= 4 {
+		arg := strings.TrimSpace(os.Args[3])
+		if arg == "--help" || arg == "-h" || arg == "help" {
+			fmt.Println("usage: engram cloud enroll <project>")
+			fmt.Println("Enroll a local-first project for explicit cloud replication.")
+			return
+		}
+	}
 	if len(os.Args) < 4 || strings.TrimSpace(os.Args[3]) == "" {
 		fmt.Fprintln(os.Stderr, "usage: engram cloud enroll <project>")
 		exitFunc(1)

cmd/engram/main.go

@@ -530,10 +530,11 @@ func main() {
 		exitFunc(1)
 	}
 
-	// Check for updates on every invocation.
-	if result := checkForUpdates(version); result.Status != versioncheck.StatusUpToDate && result.Message != "" {
-		fmt.Fprintln(os.Stderr, result.Message)
-		fmt.Fprintln(os.Stderr)
+	if shouldCheckForUpdates(os.Args[1:]) {
+		printUpdateCheckResult(checkForUpdates(version))
+	}
+	if handleConfigFreeCommand(os.Args[1:]) {
+		return
 	}
 
 	cfg, cfgErr := store.DefaultConfig()
@@ -600,6 +601,50 @@ func main() {
 	}
 }
 
+func shouldCheckForUpdates(args []string) bool {
+	if len(args) == 0 {
+		return false
+	}
+	command := strings.ToLower(strings.TrimSpace(args[0]))
+	switch command {
+	case "mcp", "serve":
+		return false
+	case "cloud":
+		return len(args) < 2 || strings.ToLower(strings.TrimSpace(args[1])) != "serve"
+	}
+	return true
+}
+
+func handleConfigFreeCommand(args []string) bool {
+	if len(args) == 0 {
+		return false
+	}
+	switch strings.ToLower(strings.TrimSpace(args[0])) {
+	case "version", "--version", "-v":
+		fmt.Printf("engram %s\n", version)
+		return true
+	case "help", "--help", "-h":
+		printUsage()
+		return true
+	case "cloud":
+		if len(args) >= 2 {
+			subcommand := strings.ToLower(strings.TrimSpace(args[1]))
+			if subcommand == "--help" || subcommand == "-h" || subcommand == "help" {
+				cmdCloud(store.Config{})
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func printUpdateCheckResult(result versioncheck.CheckResult) {
+	if result.Status != versioncheck.StatusUpToDate && result.Message != "" {
+		fmt.Fprintln(os.Stderr, result.Message)
+		fmt.Fprintln(os.Stderr)
+	}
+}
+
 // ─── Commands ────────────────────────────────────────────────────────────────
 
 func cmdServe(cfg store.Config) {
@@ -882,7 +927,13 @@ func cmdSave(cfg store.Config) {
 	if project != "" {
 		sessionID = "manual-save-" + project
 	}
-	s.CreateSession(sessionID, project, "")
+	cwd, err := os.Getwd()
+	if err != nil {
+		fatal(err)
+	}
+	if err := s.CreateSession(sessionID, project, cwd); err != nil {
+		fatal(err)
+	}
 	id, err := storeAddObservation(s, store.AddObservationParams{
 		SessionID: sessionID,
 		Type:      typ,
@@ -1113,6 +1164,9 @@ func cmdSync(cfg store.Config) {
 	projectProvided := false
 	for i := 2; i < len(os.Args); i++ {
 		switch os.Args[i] {
+		case "--help", "-h", "help":
+			printSyncUsage()
+			return
 		case "--import":
 			doImport = true
 		case "--status":
@@ -1317,6 +1371,12 @@ func cmdSync(cfg store.Config) {
 	fmt.Printf("  git add .engram/ && git commit -m \"sync engram memories\"\n")
 }
 
+func printSyncUsage() {
+	fmt.Println("usage: engram sync [--import | --status] [--all] [--cloud --project PROJECT]")
+	fmt.Println("Local sync exports project-scoped chunks to .engram/ by default.")
+	fmt.Println("Cloud sync requires an explicit --project and never runs from --help.")
+}
+
 // storeAdapter wraps *store.Store to satisfy obsidian.StoreReader.
 // The real store.Stats() returns (*store.Stats, error); the interface expects *store.Stats.
 type storeAdapter struct{ s *store.Store }

cmd/engram/main_extra_test.go

@@ -563,6 +563,114 @@ func TestCloudCommandIsolationDoesNotMutateLocalState(t *testing.T) {
 	}
 }
 
+func TestCmdSaveCreatesManualSessionWithCWDDirectory(t *testing.T) {
+	stubExitWithPanic(t)
+	stubRuntimeHooks(t)
+
+	cfg := testConfig(t)
+	cwd := t.TempDir()
+	oldWd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("get wd: %v", err)
+	}
+	if err := os.Chdir(cwd); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWd) })
+
+	withArgs(t, "engram", "save", "Manual title", "Manual content", "--project", "manual-proj")
+	_, stderr, recovered := captureOutputAndRecover(t, func() { cmdSave(cfg) })
+	if recovered != nil || stderr != "" {
+		t.Fatalf("cmdSave should succeed, panic=%v stderr=%q", recovered, stderr)
+	}
+
+	s, err := store.New(cfg)
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	session, err := s.GetSession("manual-save-manual-proj")
+	if err != nil {
+		t.Fatalf("get manual session: %v", err)
+	}
+	wantDir, err := filepath.EvalSymlinks(cwd)
+	if err != nil {
+		t.Fatalf("resolve cwd symlinks: %v", err)
+	}
+	gotDir, err := filepath.EvalSymlinks(session.Directory)
+	if err != nil {
+		t.Fatalf("resolve session directory symlinks: %v", err)
+	}
+	if gotDir != wantDir {
+		t.Fatalf("manual session directory = %q, want %q", session.Directory, cwd)
+	}
+}
+
+func TestCloudEnrollAndSyncHelpDoNotMutateLocalState(t *testing.T) {
+	stubExitWithPanic(t)
+	stubRuntimeHooks(t)
+
+	for _, tc := range []struct {
+		name string
+		args []string
+		run  func(store.Config)
+	}{
+		{name: "cloud enroll help", args: []string{"engram", "cloud", "enroll", "--help"}, run: cmdCloud},
+		{name: "sync help", args: []string{"engram", "sync", "--help"}, run: cmdSync},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			tmpHome := t.TempDir()
+			cfg := testConfig(t)
+			cfg.DataDir = filepath.Join(tmpHome, ".engram")
+
+			withArgs(t, tc.args...)
+			stdout, stderr, recovered := captureOutputAndRecover(t, func() { tc.run(cfg) })
+			if recovered != nil || stderr != "" {
+				t.Fatalf("help should return cleanly, panic=%v stderr=%q stdout=%q", recovered, stderr, stdout)
+			}
+			if !strings.Contains(stdout, "usage:") {
+				t.Fatalf("expected usage output, got %q", stdout)
+			}
+			if _, err := os.Stat(filepath.Join(cfg.DataDir, "engram.db")); err == nil {
+				t.Fatalf("help should not create local database")
+			}
+		})
+	}
+}
+
+func TestUpdateChecksSkipCriticalStartupCommands(t *testing.T) {
+	if shouldCheckForUpdates([]string{"mcp"}) {
+		t.Fatal("mcp startup must not run update check")
+	}
+	if shouldCheckForUpdates([]string{"serve"}) {
+		t.Fatal("serve startup must not run update check")
+	}
+	if shouldCheckForUpdates([]string{"cloud", "serve"}) {
+		t.Fatal("cloud serve startup must not run update check")
+	}
+	if !shouldCheckForUpdates([]string{"version"}) {
+		t.Fatal("normal commands should keep update output")
+	}
+}
+
+func TestMainCloudHelpDoesNotCreateLocalDatabase(t *testing.T) {
+	stubRuntimeHooks(t)
+	dataDir := filepath.Join(t.TempDir(), ".engram")
+	t.Setenv("ENGRAM_DATA_DIR", dataDir)
+	withArgs(t, "engram", "cloud", "--help")
+
+	stdout, stderr, recovered := captureOutputAndRecover(t, func() { main() })
+	if recovered != nil || stderr != "" {
+		t.Fatalf("cloud help should return cleanly, panic=%v stderr=%q stdout=%q", recovered, stderr, stdout)
+	}
+	if !strings.Contains(stdout, "usage: engram cloud") {
+		t.Fatalf("expected cloud usage output, got %q", stdout)
+	}
+	if _, err := os.Stat(filepath.Join(dataDir, "engram.db")); err == nil {
+		t.Fatal("cloud help should not create local database")
+	}
+}
+
 func TestCmdCloudStatusDistinguishesAuthAndSyncReadiness(t *testing.T) {
 	stubExitWithPanic(t)
 	stubRuntimeHooks(t)