RabbitLabs/calculator
Watch
5
0
Fork
You've already forked calculator
 0
Code Issues 20 Pull requests 2 Projects 1 Releases Packages Wiki Activity Actions

Ability to save interactive session to a text file #31

New issue
Open
opened 2025-10-20 12:40:26 +01:00 by Vylpes · 3 comments
Vylpes commented 2025-10-20 12:40:26 +01:00
Owner
Copy link

Milestone: 0.3.0
Story Points: 5

AS a user in the calculator CLI interactive REPL
I WANT to save my session transcript to a text file
SO THAT I can keep a record of the expressions I evaluated and their results

Acceptance Criteria

GIVEN I run calculator cli with stdin attached to a TTY (interactive REPL mode)
WHEN I evaluate one or more expressions during the session
THEN the CLI maintains an in-memory transcript of each non-empty expression entered (excluding REPL control commands)

GIVEN I am in an interactive REPL session with transcript entries
WHEN I enter the command save
THEN the transcript is written to calculator-session.txt in the current working directory
AND a confirmation message is printed (e.g. Session saved to calculator-session.txt)
AND the REPL continues (I am not logged out)

GIVEN I am in an interactive REPL session with transcript entries
WHEN I enter the command save <path> (e.g. save /tmp/my-session.txt or save notes/calc.log)
THEN the transcript is written to the specified file path
AND parent directories are created if they do not exist
AND a confirmation message is printed with the resolved path
AND the REPL continues

GIVEN a transcript entry was evaluated successfully
WHEN the session file is written
THEN the entry appears as one line: {expression} = {result} (matching the numeric result shown in the REPL)

GIVEN a transcript entry failed evaluation
WHEN the session file is written
THEN the entry appears as one line: {expression} -> ERROR: {message}

GIVEN I run save or save <path> when the transcript is empty (no expressions evaluated yet)
WHEN the command is processed
THEN a clear message is shown that there is nothing to save
AND no file is created (or an existing target file is not truncated)

GIVEN the target file already exists
WHEN I run save or save <path>
THEN the file is overwritten with the current transcript (no interactive overwrite prompt)

GIVEN I enter REPL control commands (quit, exit, save, save <path>)
WHEN the CLI processes them
THEN they are not added to the transcript and are not evaluated as expressions

GIVEN I run calculator cli "2 + 3" (single-expression mode)
WHEN stdin may or may not be piped
THEN behaviour is unchanged — this story does not add session saving to single-expression mode

GIVEN I run calculator cli with stdin that is not a TTY (piped/redirected batch mode from #30)
WHEN expressions are read from stdin
THEN behaviour is unchanged — this story does not write session logs in batch mode

GIVEN I run calculator cli interactively as today
WHEN I enter expressions, empty lines, quit, or exit
THEN existing interactive behaviour is unchanged aside from the new save commands

Subtasks

  • Add in-memory session transcript buffer in interactive REPL loop
  • Implement save and save <path> REPL commands (path parsing, directory creation, overwrite)
  • Define transcript line format for success and error entries
  • Handle empty-transcript save gracefully
  • Add unit/integration tests for save commands and regression checks for existing REPL/batch/single-expression modes
  • Update CLI documentation/help text for save commands

Notes

  • Current interactive REPL (src/cli.rs on release/0.1.0): banner, > prompt, prints = {result} on success, errors to stderr, quit/exit to end
  • Related: #30 (piped stdin batch mode) is separate and does not write session logs
  • Related: #25 (session history cycling) is separate; saving persists transcript to disk, not in-memory arrow-key history
  • Default filename calculator-session.txt is a convention; override with save <path>
  • GUI mode is out of scope
  • Expression syntax and evaluation rules follow whatever the engine supports at implementation time
Milestone: 0.3.0 Story Points: 5 --- AS a user in the calculator CLI interactive REPL I WANT to save my session transcript to a text file SO THAT I can keep a record of the expressions I evaluated and their results ## Acceptance Criteria GIVEN I run `calculator cli` with stdin attached to a TTY (interactive REPL mode) WHEN I evaluate one or more expressions during the session THEN the CLI maintains an in-memory transcript of each non-empty expression entered (excluding REPL control commands) GIVEN I am in an interactive REPL session with transcript entries WHEN I enter the command `save` THEN the transcript is written to `calculator-session.txt` in the current working directory AND a confirmation message is printed (e.g. `Session saved to calculator-session.txt`) AND the REPL continues (I am not logged out) GIVEN I am in an interactive REPL session with transcript entries WHEN I enter the command `save <path>` (e.g. `save /tmp/my-session.txt` or `save notes/calc.log`) THEN the transcript is written to the specified file path AND parent directories are created if they do not exist AND a confirmation message is printed with the resolved path AND the REPL continues GIVEN a transcript entry was evaluated successfully WHEN the session file is written THEN the entry appears as one line: `{expression} = {result}` (matching the numeric result shown in the REPL) GIVEN a transcript entry failed evaluation WHEN the session file is written THEN the entry appears as one line: `{expression} -> ERROR: {message}` GIVEN I run `save` or `save <path>` when the transcript is empty (no expressions evaluated yet) WHEN the command is processed THEN a clear message is shown that there is nothing to save AND no file is created (or an existing target file is not truncated) GIVEN the target file already exists WHEN I run `save` or `save <path>` THEN the file is overwritten with the current transcript (no interactive overwrite prompt) GIVEN I enter REPL control commands (`quit`, `exit`, `save`, `save <path>`) WHEN the CLI processes them THEN they are **not** added to the transcript and are **not** evaluated as expressions GIVEN I run `calculator cli "2 + 3"` (single-expression mode) WHEN stdin may or may not be piped THEN behaviour is unchanged — this story does not add session saving to single-expression mode GIVEN I run `calculator cli` with stdin that is **not** a TTY (piped/redirected batch mode from #30) WHEN expressions are read from stdin THEN behaviour is unchanged — this story does not write session logs in batch mode GIVEN I run `calculator cli` interactively as today WHEN I enter expressions, empty lines, `quit`, or `exit` THEN existing interactive behaviour is unchanged aside from the new `save` commands ## Subtasks - [ ] Add in-memory session transcript buffer in interactive REPL loop - [ ] Implement `save` and `save <path>` REPL commands (path parsing, directory creation, overwrite) - [ ] Define transcript line format for success and error entries - [ ] Handle empty-transcript save gracefully - [ ] Add unit/integration tests for save commands and regression checks for existing REPL/batch/single-expression modes - [ ] Update CLI documentation/help text for `save` commands ## Notes - Current interactive REPL (`src/cli.rs` on `release/0.1.0`): banner, `>` prompt, prints `= {result}` on success, errors to stderr, `quit`/`exit` to end - Related: #30 (piped stdin batch mode) is separate and does not write session logs - Related: #25 (session history cycling) is separate; saving persists transcript to disk, not in-memory arrow-key history - Default filename `calculator-session.txt` is a convention; override with `save <path>` - GUI mode is out of scope - Expression syntax and evaluation rules follow whatever the engine supports at implementation time
Vylpes added this to the 0.3.0 milestone 2025-11-25 17:25:02 +00:00
Smithy-bot commented 2026-09-18 12:14:42 +01:00
Member
Copy link

Fleshed out acceptance criteria for saving an interactive CLI session to a text file.

Key points:

  • CLI interactive REPL only — no GUI changes
  • New REPL commands: save (default file calculator-session.txt in cwd) and save <path> (user-specified path), matching existing quit/exit command style
  • Session transcript accumulates from REPL start; each evaluated line is written as {expression} = {result} (successful) or {expression} -> ERROR: {message} (failed)
  • save does not exit the session; user can continue calculating and save again (overwrites the target file)
  • Single-expression mode (calculator cli "expr") and piped stdin batch mode (#30) remain unchanged

Criteria are specific enough to estimate. Moving to needs/estimate.

Fleshed out acceptance criteria for saving an interactive CLI session to a text file. Key points: - **CLI interactive REPL only** — no GUI changes - New REPL commands: **`save`** (default file `calculator-session.txt` in cwd) and **`save <path>`** (user-specified path), matching existing `quit`/`exit` command style - Session transcript accumulates from REPL start; each evaluated line is written as `{expression} = {result}` (successful) or `{expression} -> ERROR: {message}` (failed) - **`save` does not exit** the session; user can continue calculating and save again (overwrites the target file) - Single-expression mode (`calculator cli "expr"`) and piped stdin batch mode (#30) remain unchanged Criteria are specific enough to estimate. Moving to `needs/estimate`.
Smithy-bot commented 2026-09-19 12:06:52 +01:00
Member
Copy link

Story point estimate for saving an interactive CLI session to a text file.

Acceptance criteria are specific enough to size. Breakdown:

Area Points
In-memory transcript buffer + REPL command dispatch (save / save <path> alongside quit/exit) 2
File write path (default filename, user path, mkdir, overwrite, confirmation messages) 1
Transcript line formats (success/error), empty-transcript handling, exclude control commands 1
Unit/integration tests + CLI help/docs + regression for single-expression and piped batch modes 1
Total 5

Comparable scope to #30 (piped stdin batch mode, also estimated at 5). GUI, single-expression mode, and piped batch mode remain explicitly out of scope.

Setting Story Points: 5 on the issue body. Moving to needs/tests.

Story point estimate for saving an interactive CLI session to a text file. Acceptance criteria are specific enough to size. Breakdown: | Area | Points | |------|--------| | In-memory transcript buffer + REPL command dispatch (`save` / `save <path>` alongside `quit`/`exit`) | 2 | | File write path (default filename, user path, mkdir, overwrite, confirmation messages) | 1 | | Transcript line formats (success/error), empty-transcript handling, exclude control commands | 1 | | Unit/integration tests + CLI help/docs + regression for single-expression and piped batch modes | 1 | | **Total** | **5** | Comparable scope to #30 (piped stdin batch mode, also estimated at 5). GUI, single-expression mode, and piped batch mode remain explicitly out of scope. Setting **Story Points: 5** on the issue body. Moving to `needs/tests`.
Smithy-bot commented 2026-09-20 12:01:53 +01:00
Member
Copy link

QA Testing Scripts

Story: Ability to save interactive session to a text file
Estimate: 5 story points

TC-01 — Transcript accumulates during interactive REPL session

  • Given I run calculator cli with stdin attached to a TTY (interactive REPL mode)
  • When I evaluate 2 + 3 and then 10 / 2
  • Then both expressions are recorded in the in-memory transcript (verified via a subsequent save)
  • And the REPL continues normally after each evaluation

TC-02 — Default save writes calculator-session.txt in cwd

  • Given I am in an interactive REPL session with at least one evaluated expression
  • When I enter save
  • Then a file calculator-session.txt is created in the current working directory
  • And a confirmation message is printed (e.g. Session saved to calculator-session.txt)
  • And the REPL continues (I am not logged out)

TC-03 — save <path> writes to a user-specified file

  • Given I am in an interactive REPL session with transcript entries
  • When I enter save /tmp/my-session.txt (or save notes/calc.log)
  • Then the transcript is written to the specified file path
  • And a confirmation message is printed with the resolved path
  • And the REPL continues

TC-04 — save <path> creates parent directories if missing

  • Given I am in an interactive REPL session with transcript entries
  • And the directory notes/sessions/ does not exist
  • When I enter save notes/sessions/test.log
  • Then parent directories are created
  • And the transcript is written to notes/sessions/test.log

TC-05 — Successful evaluation line format in saved file

  • Given I am in an interactive REPL session
  • When I evaluate 2 + 3 (which prints = 5 in the REPL) and then run save
  • Then calculator-session.txt contains a line: 2 + 3 = 5

TC-06 — Failed evaluation line format in saved file

  • Given I am in an interactive REPL session
  • When I evaluate an invalid expression (e.g. 5 + *) and then run save
  • Then the saved file contains a line: 5 + * -> ERROR: {message}
  • And {message} matches the error shown in the REPL/stderr

TC-07 — Empty transcript: clear message, no file created

  • Given I start an interactive REPL session and evaluate no expressions
  • When I enter save
  • Then a clear message is shown that there is nothing to save
  • And calculator-session.txt is not created

TC-08 — Empty transcript: existing target file is not truncated

  • Given a file calculator-session.txt already exists with content previous session
  • And I start a new interactive REPL session without evaluating any expressions
  • When I enter save
  • Then a clear message is shown that there is nothing to save
  • And the existing file still contains previous session (not truncated)

TC-09 — Overwrite existing file without interactive prompt

  • Given calculator-session.txt already exists with old content
  • And I am in an interactive REPL session with new transcript entries
  • When I enter save
  • Then the file is overwritten with the current transcript (no overwrite confirmation prompt)
  • And old content is replaced

TC-10 — REPL control commands are excluded from transcript

  • Given I am in an interactive REPL session
  • When I evaluate 2 + 2, then enter save, then quit
  • Then the saved file contains only 2 + 2 = 4
  • And save, save calculator-session.txt, quit, and exit do not appear as transcript entries

TC-11 — save does not evaluate as an expression

  • Given I am in an interactive REPL session
  • When I enter save (with or without prior expressions)
  • Then the CLI does not attempt to evaluate save as a mathematical expression
  • And no expression error is shown for the save command itself

TC-12 — Multiple saves during one session (overwrite on each save)

  • Given I am in an interactive REPL session
  • When I evaluate 1 + 1, run save, then evaluate 3 + 3, and run save again
  • Then calculator-session.txt contains both lines after the second save
  • And the REPL remains active throughout

TC-13 — Single-expression mode unchanged (regression)

  • Given the calculator CLI is available
  • When I run calculator cli "2 + 3"
  • Then 5 is printed to stdout (result only)
  • And no session file is created
  • And behaviour matches pre-story implementation

TC-14 — Piped stdin batch mode unchanged (regression, #30)

  • Given the calculator CLI is available
  • When I run echo "2 + 3" | calculator cli (non-TTY stdin, no expression argument)
  • Then 5 is printed to stdout
  • And no session file is created
  • And behaviour matches #30 batch mode

TC-15 — Existing interactive REPL behaviour unchanged (regression)

  • Given I run calculator cli with stdin attached to a TTY
  • When the CLI starts
  • Then the existing interactive banner and > prompt are shown
  • And entering 2 + 3 prints = 5 (or equivalent existing format)
  • And empty lines are handled as today
  • And quit or exit ends the session normally

TC-16 — CLI help text documents save commands

  • Given the calculator CLI is available
  • When I check CLI help/documentation for interactive mode
  • Then save and save <path> are documented alongside quit/exit

TC-17 — Automated tests cover save scenarios

  • Given the project test suite
  • When I run the unit/integration tests added for this story
  • Then tests pass for: default save, custom path, mkdir, success/error line formats, empty transcript, overwrite, control-command exclusion, and regression checks for single-expression and piped batch modes

TC-18 — GUI mode unaffected (regression)

  • Given the calculator GUI is available
  • When I launch and use the GUI normally
  • Then behaviour is unchanged (this story is CLI interactive REPL only)

Criteria are specific enough to test. Moving to needs/approval for human sign-off before implementation.

## QA Testing Scripts **Story:** Ability to save interactive session to a text file **Estimate:** 5 story points ### TC-01 — Transcript accumulates during interactive REPL session - **Given** I run `calculator cli` with stdin attached to a TTY (interactive REPL mode) - **When** I evaluate `2 + 3` and then `10 / 2` - **Then** both expressions are recorded in the in-memory transcript (verified via a subsequent `save`) - **And** the REPL continues normally after each evaluation ### TC-02 — Default `save` writes `calculator-session.txt` in cwd - **Given** I am in an interactive REPL session with at least one evaluated expression - **When** I enter `save` - **Then** a file `calculator-session.txt` is created in the current working directory - **And** a confirmation message is printed (e.g. `Session saved to calculator-session.txt`) - **And** the REPL continues (I am not logged out) ### TC-03 — `save <path>` writes to a user-specified file - **Given** I am in an interactive REPL session with transcript entries - **When** I enter `save /tmp/my-session.txt` (or `save notes/calc.log`) - **Then** the transcript is written to the specified file path - **And** a confirmation message is printed with the resolved path - **And** the REPL continues ### TC-04 — `save <path>` creates parent directories if missing - **Given** I am in an interactive REPL session with transcript entries - **And** the directory `notes/sessions/` does not exist - **When** I enter `save notes/sessions/test.log` - **Then** parent directories are created - **And** the transcript is written to `notes/sessions/test.log` ### TC-05 — Successful evaluation line format in saved file - **Given** I am in an interactive REPL session - **When** I evaluate `2 + 3` (which prints `= 5` in the REPL) and then run `save` - **Then** `calculator-session.txt` contains a line: `2 + 3 = 5` ### TC-06 — Failed evaluation line format in saved file - **Given** I am in an interactive REPL session - **When** I evaluate an invalid expression (e.g. `5 + *`) and then run `save` - **Then** the saved file contains a line: `5 + * -> ERROR: {message}` - **And** `{message}` matches the error shown in the REPL/stderr ### TC-07 — Empty transcript: clear message, no file created - **Given** I start an interactive REPL session and evaluate no expressions - **When** I enter `save` - **Then** a clear message is shown that there is nothing to save - **And** `calculator-session.txt` is not created ### TC-08 — Empty transcript: existing target file is not truncated - **Given** a file `calculator-session.txt` already exists with content `previous session` - **And** I start a new interactive REPL session without evaluating any expressions - **When** I enter `save` - **Then** a clear message is shown that there is nothing to save - **And** the existing file still contains `previous session` (not truncated) ### TC-09 — Overwrite existing file without interactive prompt - **Given** `calculator-session.txt` already exists with old content - **And** I am in an interactive REPL session with new transcript entries - **When** I enter `save` - **Then** the file is overwritten with the current transcript (no overwrite confirmation prompt) - **And** old content is replaced ### TC-10 — REPL control commands are excluded from transcript - **Given** I am in an interactive REPL session - **When** I evaluate `2 + 2`, then enter `save`, then `quit` - **Then** the saved file contains only `2 + 2 = 4` - **And** `save`, `save calculator-session.txt`, `quit`, and `exit` do not appear as transcript entries ### TC-11 — `save` does not evaluate as an expression - **Given** I am in an interactive REPL session - **When** I enter `save` (with or without prior expressions) - **Then** the CLI does not attempt to evaluate `save` as a mathematical expression - **And** no expression error is shown for the `save` command itself ### TC-12 — Multiple saves during one session (overwrite on each save) - **Given** I am in an interactive REPL session - **When** I evaluate `1 + 1`, run `save`, then evaluate `3 + 3`, and run `save` again - **Then** `calculator-session.txt` contains both lines after the second save - **And** the REPL remains active throughout ### TC-13 — Single-expression mode unchanged (regression) - **Given** the calculator CLI is available - **When** I run `calculator cli "2 + 3"` - **Then** `5` is printed to stdout (result only) - **And** no session file is created - **And** behaviour matches pre-story implementation ### TC-14 — Piped stdin batch mode unchanged (regression, #30) - **Given** the calculator CLI is available - **When** I run `echo "2 + 3" | calculator cli` (non-TTY stdin, no expression argument) - **Then** `5` is printed to stdout - **And** no session file is created - **And** behaviour matches #30 batch mode ### TC-15 — Existing interactive REPL behaviour unchanged (regression) - **Given** I run `calculator cli` with stdin attached to a TTY - **When** the CLI starts - **Then** the existing interactive banner and `>` prompt are shown - **And** entering `2 + 3` prints `= 5` (or equivalent existing format) - **And** empty lines are handled as today - **And** `quit` or `exit` ends the session normally ### TC-16 — CLI help text documents `save` commands - **Given** the calculator CLI is available - **When** I check CLI help/documentation for interactive mode - **Then** `save` and `save <path>` are documented alongside `quit`/`exit` ### TC-17 — Automated tests cover save scenarios - **Given** the project test suite - **When** I run the unit/integration tests added for this story - **Then** tests pass for: default save, custom path, mkdir, success/error line formats, empty transcript, overwrite, control-command exclusion, and regression checks for single-expression and piped batch modes ### TC-18 — GUI mode unaffected (regression) - **Given** the calculator GUI is available - **When** I launch and use the GUI normally - **Then** behaviour is unchanged (this story is CLI interactive REPL only) --- Criteria are specific enough to test. Moving to `needs/approval` for human sign-off before implementation.
Smithy-bot removed their assignment 2026-09-20 12:01:56 +01:00
Vylpes removed their assignment 2026-09-20 13:14:26 +01:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
cursor/11-forgejo-actions
release/0.1.0
feature/11-forgejo-actions
develop
No results found.
Labels
Clear labels
  
blocked

   
duplicate
  
needs
approval

  
needs
criteria

  
needs
estimate

  
needs
tests

  
question
  
step
doing

  
step
review

  
step
testing

  
step
todo

  
step
uat

  
type
admin

  
type
alert

  
type
bug

  
type
change

  
type
defect

  
type
dependencies

  
type
epic

  
type
idea

  
type
incident

  
type
investigation

  
type
spike

  
type
story

  
won't fix
No labels
blocked
duplicate
needs
approval
needs
criteria
needs
estimate
needs
tests
question
step
doing
step
review
step
testing
step
todo
step
uat
type
admin
type
alert
type
bug
type
change
type
defect
type
dependencies
type
epic
type
idea
type
incident
type
investigation
type
spike
type
story
won't fix
Milestone
Clear milestone
No items
No milestone
0.3.0
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
RabbitLabs/calculator#31
No description provided.