feat(cli): Node + browser CLI, exit command, Node export, BDD for both

Author: devalbo

AGENTS.md

@@ -6,7 +6,7 @@ Context for AI assistants working on this repo.
 
 **tb-solid-pod** is a browser-based personal data pod inspired by the [Solid Project](https://solidproject.org/), built with [TinyBase](https://tinybase.org/) for reactive state and LocalStorage. It is **not** a real Solid server (no LDP, no WebID-TLS); it simulates Solid-style data (personas, contacts, groups, type indexes, file metadata) in a single-page app.
 
-- **Dual interface**: graphical UI (tabs, forms, lists) + CLI terminal.
+- **Dual interface**: graphical UI (tabs, forms, lists) + CLI. The CLI runs in the **browser** (Terminal tab) and in **Node** (`npm run cli`); same commands, environment-specific persistence (LocalStorage vs `~/.tb-solid-pod/data/store.json`).
 - **Data**: personas (WebID-style), contacts (including agents), groups (org/team/group) with membership of contacts and your personas, type indexes, virtual file system with metadata, settings/preferences.
 - **Stack**: React, TinyBase, Zod, Vite, TypeScript. Vocabularies: FOAF, vCard, Dublin Core, W3C Org, `@inrupt/vocab-*`.
 
@@ -19,7 +19,7 @@ Context for AI assistants working on this repo.
 | `src/index.ts` | **Library entry** – re-exports schemas, utils, CLI, components for `import from 'tb-solid-pod'`. |
 | `src/schemas/` | Zod schemas + factory functions + **JSON Schema** (json-schema.ts via Zod v4 toJSONSchema; persona, contact, group, file, typeIndex, preferences, base). **Zod is source of truth**—no canonical Solid JSON Schema; we generate from Zod. Static files: `npm run generate:schemas` → `schema/*.json`. |
 | `src/utils/` | settings, storeExport, typeIndex helpers, validation. |
-| `src/cli/` | CliTerminal, command registry, parse-args, types. |
+| `src/cli/` | CliTerminal (browser), run-node.tsx (Node entry), node-store.ts (file persister), command registry, parse-args, types. |
 | `src/components/` | PersonaList/Form, ContactList/Form, GroupList/Form, MembershipManager, FileMetadataPanel. |
 | `docs/` | CODING_GUIDELINES.md, DOCUMENTATION_GUIDELINES.md, DESIGN.md, IMPLEMENTATION_PLAN.md, TEST_PLAN.md, testing/. |
 
@@ -73,8 +73,8 @@ When someone wants to use this in an app they’re working on, point them to the
 
 ## Useful docs
 
-- **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), link to Integration Guide, Getting Started (Node note, Live demo + 404 troubleshooting), Testing (unit, BDD, Storybook link), CLI command list.
-- **docs/INTEGRATION_GUIDE.md** – Step-by-step integration (install-from-GitHub vs copy-paste), store setup, Provider, components, CLI, data tables, extending.
+- **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), link to Integration Guide, Getting Started (Node note, Live demo + 404 troubleshooting), Running the CLI in the terminal (`npm run cli`, exit, single-command mode), Testing (unit, BDD, Storybook link), CLI command list.
+- **docs/INTEGRATION_GUIDE.md** – Step-by-step integration (install-from-GitHub vs copy-paste), store setup, Provider, components, CLI (browser + terminal), data tables, extending.
 - **docs/SDLC_PROCESS.md** – How changes are introduced, documented, and verified; links to Feature Checklist.
 - **docs/FEATURE_CHECKLIST.md** – Manual verification checklist ordered by dependency (foundational first); assume features are broken until verified.
 - **docs/CODING_GUIDELINES.md** – TypeScript (strict types, no sloppy types), short functions, simple React components, naming, file length.

README.md

@@ -190,6 +190,19 @@ npm install
 npm run dev
 ```
 
+## Running the CLI in the terminal
+
+You can run the same CLI from a **real terminal** (Node.js) as well as in the browser’s Terminal tab:
+
+```bash
+npm run cli
+```
+
+- **Interactive**: Full session with the same commands as the browser. Use **↑/↓** for command history and **Tab** for command-name completion.
+- **Single command**: Pass the command as arguments; output is printed and the process exits. Example: `npm run cli -- help` or `npm run cli -- contact list`.
+- **Data**: Stored in `~/.tb-solid-pod/data/store.json` (or set `TB_SOLID_POD_DATA_PATH` to a different path). Same store shape as the browser; data is not shared between browser and terminal unless you point both at the same file.
+
+
 ## CLI Commands
 
 ```
@@ -203,6 +216,7 @@ config list|get|set|reset
 pwd|cd|ls|cat|touch|mkdir|rm  File system operations
 export|import                 Data portability
 clear                         Clear terminal
+exit                          Exit the CLI (Node terminal only)
 ```
 
 ## Testing

docs/FEATURE_CHECKLIST.md

@@ -54,13 +54,15 @@ Must work to access features.
 
 ## Level 3: CLI Terminal
 
-Required for CLI-based features.
+Required for CLI-based features. The same CLI runs in the **browser** (Terminal tab) and in **Node** (`npm run cli`). BDD tests cover both (Scenario Outline: browser \| terminal).
 
 - [x] CLI prompt accepts input
 - [x] `help` command shows available commands
 - [x] `clear` command clears terminal
 - [x] Command history (up arrow) works
 - [x] Unknown command shows error message
+- [x] `exit` command quits Node CLI; in browser shows message that exit is terminal-only
+- [x] In Node: `export` prints JSON; `export --download` writes file to cwd
 
 ---
 
@@ -269,7 +271,7 @@ Depends on: Personas, Type Indexes
 
 ### Unit Tests
 - [x] `npm test` runs without errors
-- [x] 385+ tests passing
+- [x] 392+ tests passing
 - [x] Coverage meets 80% threshold
 
 ### Storybook
@@ -280,10 +282,11 @@ Depends on: Personas, Type Indexes
 - [x] FileMetadataPanel stories render
 
 ### BDD/E2E
-- [x] `npm run test:e2e` runs (with dev server running)
+- [x] `npm run test:e2e` runs (dev server required for browser scenarios; terminal scenarios run Node CLI)
 - [x] App shell scenarios pass
-- [x] CLI contact scenarios pass
-- [x] CLI persona scenarios pass
+- [x] CLI contact scenarios pass (browser and terminal)
+- [x] CLI persona scenarios pass (browser and terminal)
+- [x] CLI navigation scenarios pass (browser and terminal)
 
 ---
 

docs/IMPLEMENTATION_PLAN.md

@@ -4,10 +4,10 @@
 
 Phases 1–7 complete. See [Feature Checklist](#feature-checklist) for detailed status.
 
-The app has a working browser-based CLI and file browser UI with:
+The app has a working CLI (browser Terminal tab and Node: `npm run cli`) and file browser UI with:
 - Basic file/folder CRUD operations
-- TinyBase persistence with LocalStorage
-- Import/export functionality
+- TinyBase persistence: LocalStorage (browser) or file (Node: `~/.tb-solid-pod/data/store.json`)
+- Import/export functionality (export in Node: print JSON or `export --download` to file)
 - Tab-based navigation (Data Browser / Personas / Contacts / Groups / Terminal)
 - Persona management (Phase 1)
 - Contact management with search/filter (Phase 2)

docs/INTEGRATION_GUIDE.md

@@ -2,7 +2,7 @@
 
 This guide explains how to integrate **tb-solid-pod** into an application you are building. It is for developers who want to add Solid-style personas, contacts, groups, type indexes, or file metadata to their app, either by installing the package from GitHub or by copying source files.
 
-**Terms:** **TinyBase** is the reactive store and persistence library used by this project. **JSON-LD** (JavaScript Object Notation for Linked Data) is the data format used for personas, contacts, and groups. **CLI** (command-line interface) refers to the in-app terminal provided by the library.
+**Terms:** **TinyBase** is the reactive store and persistence library used by this project. **JSON-LD** (JavaScript Object Notation for Linked Data) is the data format used for personas, contacts, and groups. **CLI** (command-line interface) refers to the terminal provided by the library: in-app (browser Terminal tab) or Node (`npm run cli`).
 
 ## Two ways to integrate
 
@@ -223,7 +223,9 @@ Settings are stored in TinyBase **values** (not tables):
 
 ## Adding the CLI (Optional)
 
-If you want the terminal interface:
+The CLI runs in **two environments**: (1) in-app Terminal tab in the browser, and (2) from a real terminal (Node.js).
+
+### In the browser
 
 ```tsx
 import { CliTerminal } from 'tb-solid-pod';  // or from your cli
@@ -237,6 +239,10 @@ import { CliTerminal } from 'tb-solid-pod';  // or from your cli
 />
 ```
 
+### In the terminal (Node.js)
+
+From the repo: `npm run cli`. Same commands as the browser. Data is stored in `~/.tb-solid-pod/data/store.json` (override with `TB_SOLID_POD_DATA_PATH`). Interactive mode supports **↑/↓** history and **Tab** completion for command names. Use **`exit`** to quit. **Export:** `export` prints JSON to the terminal; `export --download` writes a file to the current directory (Node has no clipboard). Single-command mode: `npm run cli -- help` or `npm run cli -- contact list`.
+
 ---
 
 ## Customizing the Base URL

docs/TEST_PLAN.md

@@ -63,7 +63,7 @@
 "test:run": "vitest run"
 ```
 
-**Total: 385 tests passing**
+**Total: 392 tests passing** (includes CLI registry test for exit command)
 
 ---
 
@@ -120,7 +120,7 @@
 
 See [docs/testing/bdd-tests.md](testing/bdd-tests.md) for full details.
 
-**Testing boundary:** The same doc defines [what is automated vs manual](testing/bdd-tests.md#testing-boundary-automated-vs-manual): app shell, tab navigation, Contacts/Personas UI, CLI help/clear/contact/persona are covered by BDD; CLI group/file/files/config/data/typeindex, Groups UI, forms, file browser, settings, export/import, and future features (pod connect, sync, ACL) are left for manual verification until scenarios are added.
+**Testing boundary:** The same doc defines [what is automated vs manual](testing/bdd-tests.md#testing-boundary-automated-vs-manual): app shell, tab navigation, Contacts/Personas UI, CLI help/clear/contact/persona/navigation are covered by BDD in **both browser and terminal** (Scenario Outline); CLI group/file/files/config/data/typeindex, Groups UI, forms, file browser, settings, export/import, and future features (pod connect, sync, ACL) are left for manual verification until scenarios are added.
 
 ### npm Scripts Added
 ```json
@@ -147,7 +147,7 @@ See [docs/testing/bdd-tests.md](testing/bdd-tests.md) for full details.
 
 ## Verification Checklist
 
-- [x] `npm test` - All unit tests pass (385 tests)
+- [x] `npm test` - All unit tests pass (392 tests)
 - [x] `npm run test:coverage` - Coverage meets 80% threshold
 - [x] `npm run storybook` - All stories render without errors
 - [ ] `npm run test:e2e` - All BDD scenarios pass (run with server on 5173; see docs/testing/bdd-tests.md)

docs/USE_CASES.md

@@ -14,7 +14,7 @@ You can use tb-solid-pod in three ways; the use cases below apply across them.
 |----------|--------------|----------------|
 | **Schemas only** | Zod schemas, factory functions, types, JSON Schema | You need the data shapes and validation; no UI or store layout required. |
 | **Schemas + store** | Same as above, plus a TinyBase store with the expected tables and values | You want to read/write personas, contacts, groups, files, and settings in a standard layout. |
-| **Schemas + store + components (and optionally CLI)** | Full UI: lists, forms, membership manager, file metadata panel, terminal | You want ready-made React components and/or the CLI for power users. |
+| **Schemas + store + components (and optionally CLI)** | Full UI: lists, forms, membership manager, file metadata panel; CLI in browser (Terminal tab) or Node (`npm run cli`) | You want ready-made React components and/or the CLI for power users. |
 
 Store setup and table layout are described in the [README Integration Guide](../README.md#integration-guide) and summarized in [Data tables](#data-tables) below.
 

docs/testing/bdd-tests.md

@@ -58,6 +58,10 @@ These are implemented in `tests/features/*.feature` and run with Playwright.
 
 **Total:** Six feature files; scenarios above are the current automated boundary. The dev server must be running (see [Starting the app](#starting-the-app)); BDD does not start it.
 
+### CLI in browser vs terminal (Scenario Outline)
+
+The same CLI scenarios run **in the browser** (Terminal tab) and **in the terminal** (Node CLI spawned with piped stdin). One feature file per area (e.g. `cli-contacts.feature`) uses a **Scenario Outline** with `Examples: | context | browser | terminal |`. The step "Given I have the CLI in the <context>" either opens the Terminal tab (browser) or spawns `npx tsx src/cli/run-node.tsx` with a unique temp store path (terminal). "When I run the command" and "Then I should see ... in the output" branch on context. Run with the same command as other E2E: `npm run test:e2e` (dev server must be running for browser; terminal runs without it). In Node, `exit` quits the process; `export` prints JSON (or `--download` writes a file). See README and [INTEGRATION_GUIDE.md](../INTEGRATION_GUIDE.md) for full CLI usage.
+
 ### Not yet automated (manual verification)
 
 These are either out of scope for the current BDD suite or not yet implemented as Gherkin scenarios. Verify them manually (or extend the feature files later).