Skip to content

Commit 3e028fa

Browse files
author
codeasier
committed
refactor: rename use to focus and add device persistence
Rename the database selection system from "context" to "focus" to avoid confusion with LLM context, and replace the vague "use" command with "focus" which better conveys setting the current analysis target. - pt-snap use -> pt-snap focus (with new --device/-d option) - context.json -> focus.json, current_db_path -> db_path - Add device_id persistence alongside db_path - Query auto-uses focused device when --device is not specified - Backward compat: old current_db_path key still readable - Update all docs, tests, and completion functions Fixes #32
1 parent 3fad27b commit 3e028fa

14 files changed

Lines changed: 742 additions & 459 deletions

‎README.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,13 @@ pip install -e .
1313
## Quick Start
1414

1515
```bash
16-
# Set the snapshot database (saves context for future queries)
17-
pt-snap use examples/snapshot_expandable.pkl.db
16+
# Set the snapshot database and device
17+
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
1818

1919
# List available queries
2020
pt-snap query --list
2121

22-
# Run a query
22+
# Run a query (automatically uses the focused device)
2323
pt-snap query --template-use memory_summary
2424

2525
# Detect potential memory leaks
@@ -32,7 +32,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
3232

3333
| Command | Description |
3434
|---------|-------------|
35-
| `pt-snap use` | Set and manage snapshot database context |
35+
| `pt-snap focus` | Set and manage analysis focus (database + device) |
3636
| `pt-snap query` | Run memory analysis queries |
3737
| `pt-snap config` | Manage global configuration |
3838

@@ -41,7 +41,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
4141
| Topic | Guide |
4242
|-------|-------|
4343
| Getting started | [Quick Start](docs/en/quickstart.md) |
44-
| Managing contexts | [Context Management](docs/en/context-management.md) |
44+
| Managing focus | [Focus Management](docs/en/focus-management.md) |
4545
| Running queries | [Querying](docs/en/querying.md) |
4646
| Database format | [SnapshotDB Schema](docs/en/database.md) |
4747
| Python API | [ResultMapper API](docs/en/result-mapper-api.md) |
@@ -63,7 +63,8 @@ pt-snap-cli/
6363
├── src/
6464
│ └── pt_snap_cli/
6565
│ ├── cli.py # CLI entry point
66-
│ ├── context.py # Context management
66+
│ ├── context.py # Database context manager
67+
│ ├── config.py # Focus management
6768
│ ├── query/
6869
│ │ ├── builder.py # Query builder
6970
│ │ ├── executor.py # Query executor

‎README_zh.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,13 @@ pip install -e .
1313
## 快速开始
1414

1515
```bash
16-
# 设置快照数据库(保存上下文供后续查询使用)
17-
pt-snap use examples/snapshot_expandable.pkl.db
16+
# 设置快照数据库和设备
17+
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
1818

1919
# 列出可用查询
2020
pt-snap query --list
2121

22-
# 运行查询
22+
# 运行查询(自动使用 focus 中设置的设备)
2323
pt-snap query --template-use memory_summary
2424

2525
# 检测潜在内存泄漏
@@ -32,7 +32,7 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
3232

3333
| 命令 | 说明 |
3434
|------|------|
35-
| `pt-snap use` | 设置和管理快照数据库上下文 |
35+
| `pt-snap focus` | 设置和管理分析焦点(数据库 + 设备) |
3636
| `pt-snap query` | 运行内存分析查询 |
3737
| `pt-snap config` | 管理全局配置 |
3838

@@ -41,7 +41,7 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
4141
| 主题 | 指南 |
4242
|------|------|
4343
| 入门指南 | [Quick Start](docs/zh/quickstart.md) |
44-
| Context 管理 | [Context Management](docs/zh/context-management.md) |
44+
| Focus 管理 | [Focus Management](docs/zh/focus-management.md) |
4545
| 运行查询 | [Querying](docs/zh/querying.md) |
4646
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
4747
| Python API | [ResultMapper API](docs/zh/result-mapper-api.md) |
@@ -63,7 +63,8 @@ pt-snap-cli/
6363
├── src/
6464
│ └── pt_snap_cli/
6565
│ ├── cli.py # CLI 入口
66-
│ ├── context.py # 上下文管理
66+
│ ├── context.py # 数据库连接管理器
67+
│ ├── config.py # 焦点管理
6768
│ ├── query/
6869
│ │ ├── builder.py # 查询构建器
6970
│ │ ├── executor.py # 查询执行器

‎docs/en/context-management.md‎

Lines changed: 0 additions & 104 deletions
This file was deleted.

‎docs/en/focus-management.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Focus Management
2+
3+
[中文](../zh/focus-management.md) | English
4+
5+
`pt-snap` supports project-scoped focus so different terminals, agents, or working directories can analyze different databases and devices without interfering with each other.
6+
7+
## Resolution Priority
8+
9+
Focus is resolved in this order:
10+
11+
1. **Explicit argument**: `pt-snap query <db_path>`
12+
2. **Environment variable**: `PT_SNAP_DB_PATH`
13+
3. **Project focus**: Nearest `.pt-snap/focus.json`, searching upward from current directory
14+
4. **Legacy global config**: `~/.config/pt-snap-cli/config.json`
15+
16+
## Set Project Database and Device
17+
18+
```bash
19+
# Set database only
20+
pt-snap focus /path/to/your/snapshot.db
21+
22+
# Set database and device together
23+
pt-snap focus /path/to/your/snapshot.db --device 0
24+
25+
# Change device only (keeps current database)
26+
pt-snap focus --device 1
27+
```
28+
29+
After successful validation, the database path and device ID are saved to `.pt-snap/focus.json` in the current directory.
30+
31+
## Session-Scoped Override
32+
33+
When a shell or agent needs an isolated database without changing project focus:
34+
35+
```bash
36+
export PT_SNAP_DB_PATH=/path/to/agent-specific/snapshot.db
37+
pt-snap query --template-use memory_summary
38+
```
39+
40+
Or validate and print the export command in one step:
41+
42+
```bash
43+
pt-snap focus /path/to/agent-specific/snapshot.db --session
44+
```
45+
46+
## View Current Focus
47+
48+
```bash
49+
pt-snap focus
50+
```
51+
52+
This shows the resolved database path, device ID, and where they came from (project focus, session env, or global config).
53+
54+
## Override Focus
55+
56+
Even with focus configured, you can temporarily specify a different database or device on the command line:
57+
58+
```bash
59+
# Uses this database temporarily, does not affect saved focus
60+
pt-snap query /path/to/other.db --template-use memory_summary
61+
62+
# Override device (ignores focused device_id)
63+
pt-snap query --template-use memory_summary --device 2
64+
```
65+
66+
## Legacy Global Configuration
67+
68+
Global configuration is kept for compatibility. For concurrent workflows, prefer project focus or session overrides.
69+
70+
```bash
71+
# Store in ~/.config/pt-snap-cli/config.json
72+
pt-snap focus /path/to/your/snapshot.db --global
73+
```
74+
75+
### Manage Global Config
76+
77+
```bash
78+
pt-snap config # View global configuration
79+
pt-snap config --path # Show config file path
80+
pt-snap config --clear # Clear global configuration
81+
```
82+
83+
## Focus File Locations
84+
85+
| Scope | File |
86+
|-------|------|
87+
| Project | `.pt-snap/focus.json` (git-ignored, per-project) |
88+
| Global | `~/.config/pt-snap-cli/config.json` |
89+
90+
### Focus File Format
91+
92+
```json
93+
{
94+
"db_path": "/path/to/your/snapshot.db",
95+
"device_id": 0
96+
}
97+
```
98+
99+
## Error Handling
100+
101+
**No focus configured:**
102+
103+
```bash
104+
pt-snap query --template-use memory_summary
105+
# Error: No database path specified and no database configured.
106+
# Use 'pt-snap focus <database_path>' to set a project database, or provide db_path argument.
107+
```
108+
109+
**Database file not found:**
110+
111+
```bash
112+
pt-snap query --template-use memory_summary
113+
# Error: Database from project focus not found: /path/to/missing.db
114+
# Use 'pt-snap focus <new_database_path>' to set a new project database, or provide db_path argument.
115+
```

‎docs/en/quickstart.md‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Quick Start
22

3-
[English](quickstart.md) | [中文](../zh/quickstart.md)
3+
[中文](../zh/quickstart.md) | English
44

55
Get up and running with `pt-snap-cli` in a few minutes.
66

@@ -12,15 +12,21 @@ pip install -e .
1212

1313
## Your First Analysis
1414

15-
### Step 1: Set the Snapshot Database
15+
### Step 1: Set the Snapshot Database and Device
1616

1717
Point `pt-snap` to your SQLite snapshot database file:
1818

1919
```bash
20-
pt-snap use examples/snapshot_expandable.pkl.db
20+
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
2121
```
2222

23-
This validates the database and saves the path to `.pt-snap/context.json` in your current directory, so you don't need to repeat it.
23+
This validates the database and saves the path and device ID to `.pt-snap/focus.json` in your current directory, so you don't need to repeat it.
24+
25+
If you only want to set the database (no device yet):
26+
27+
```bash
28+
pt-snap focus examples/snapshot_expandable.pkl.db
29+
```
2430

2531
### Step 2: List Available Queries
2632

@@ -40,12 +46,12 @@ pt-snap query --template-use memory_summary
4046
# Detect potential memory leaks
4147
pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
4248

43-
# View active memory blocks on device 0
44-
pt-snap query --template-use active_blocks --device 0
49+
# Query automatically uses the focused device, or you can override it
50+
pt-snap query --template-use active_blocks --device 1
4551
```
4652

4753
## What's Next
4854

49-
- [Context Management](context-management.md) — Learn how to manage multiple databases across projects and sessions
55+
- [Focus Management](focus-management.md) — Learn how to manage database and device focus across projects and sessions
5056
- [Querying](querying.md) — Full guide to all query templates, parameters, and output
5157
- [Database Schema](database.md) — Understand the SnapshotDB format

0 commit comments

Comments
 (0)