@agimon-ai/doompi-file-edit 0.0.1-alpha.21 → 0.0.1-alpha.23

package/README.md

@@ -1,37 +1,83 @@
 # @agimon-ai/doompi-file-edit
 
-**Every edit in the session, in one place.**
+A session-scoped file-change timeline and external-editor launcher for Pi.
 
-This package keeps a timeline of files the current Pi session changed and opens them in an
-external editor when the terminal view is not enough. It is the answer to "what did the
-agent touch?" without asking the transcript to remember every write.
+Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). Most users get
-it with the distribution.
+The package records files changed by successful `edit` and `write` calls and literal file paths detected in successful Bash changes. It presents the current session's work without relying on the transcript to remember every path.
+
+> **Alpha:** timeline and UI contracts may change between releases.
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.84.2 and Pi TUI 0.84.2
+- Git for diffs against `HEAD`
 
 ## Install
 
+DoomPi loads the Doom adapter as core. For standalone Pi:
+
 ```bash
-npm install @agimon-ai/doompi-file-edit
+pi install npm:@agimon-ai/doompi-file-edit
 ```
 
-## How it loads
+| Entry                                         | Purpose                                |
+| --------------------------------------------- | -------------------------------------- |
+| `@agimon-ai/doompi-file-edit/extensions/doom` | DoomPi adapter and Leader contribution |
+| `@agimon-ai/doompi-file-edit/extensions/pi`   | Standalone Pi adapter                  |
+| `@agimon-ai/doompi-file-edit`                 | Library API                            |
+
+## Open the timeline
+
+Use `SPC e f` in DoomPi. Select a file to inspect its diff or open it in the configured editor.
 
-Doompi loads the edit timeline as core. It is not a layer and does not appear in
-`.doom/modes.yaml`. The bare package name follows its Pi manifest and selects the Doom
-adapter; explicit `/extensions/pi` and `/extensions/doom` subpaths remain available.
+Diffs compare the working tree with Git `HEAD` and are capped at 200 lines and 256 KiB. Files outside Git history or changes that cannot be attributed to a literal Bash path may have limited timeline detail.
+
+The overlay and external-editor handoff require an interactive TUI. Headless hosts can consume the timeline services but cannot display the panel.
+
+## Configure the editor
+
+Set the shared DoomPi configuration in `~/.pi/.doom/config.yaml`:
+
+```yaml
+editor:
+  command: nvim +{line} {file}
+```
 
-## Leader
+For a standalone installation, the package falls back to `~/.pi/agent/doom-file-edit/config.yaml`. Resolution order is:
 
-`SPC e f` opens the files edited by the current session.
+1. DoomPi `editor.command`;
+2. package fallback configuration;
+3. `$VISUAL`;
+4. `$EDITOR`;
+5. `nano {file}` on Unix-like systems.
 
-## Entry points
+Only `{file}` and `{line}` placeholders are expanded. The command is split and spawned directly, not passed through a shell, so shell operators and expansions are not interpreted.
+
+## Data behavior
+
+The timeline contains file paths and Git-derived diff content from the current session. That content can be sensitive. It is stored in session-scoped package state and should be protected with the same access controls as Pi session data.
+
+## Public API
+
+```ts
+import { createFileEditContainer, fileEditExtension } from '@agimon-ai/doompi-file-edit';
+import type { FileDiff, FileEditEntry } from '@agimon-ai/doompi-file-edit';
+```
+
+The root also exports editor-resolution and timeline domain types for host integrations.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
 
-| Import                                        | Purpose               |
-| --------------------------------------------- | --------------------- |
-| `@agimon-ai/doompi-file-edit`                 | Library API           |
-| `@agimon-ai/doompi-file-edit/extensions/pi`   | Standalone Pi adapter |
-| `@agimon-ai/doompi-file-edit/extensions/doom` | Doompi adapter        |
+Maintained by [Agimon](https://agimon.ai/about).
 
 ## License
 

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@agimon-ai/doompi-file-edit",
-  "version": "0.0.1-alpha.21",
-  "description": "Pi session file edit timeline and external editor overlay",
+  "version": "0.0.1-alpha.23",
+  "description": "Pi extension for session-scoped file-change timelines and external editor workflows.",
   "keywords": [
-    "ai",
     "coding-agent",
-    "developer-tools",
     "doompi",
-    "pi-package"
+    "external-editor",
+    "file-editing",
+    "pi-coding-agent",
+    "pi-extension",
+    "session-timeline"
   ],
   "homepage": "https://agimon.ai",
   "license": "MIT",
@@ -45,10 +47,10 @@
     "cross-spawn": "7.0.6",
     "inversify": "8.2.1",
     "reflect-metadata": "0.2.2",
-    "@agimon-ai/doompi-config": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-ui": "0.0.1-alpha.21"
+    "@agimon-ai/doompi-config": "0.0.1-alpha.23",
+    "@agimon-ai/doompi-ui": "0.0.1-alpha.23",
+    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.23",
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.23"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",