ptimelog 0.9.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efde9baef775527079705c4a87dfa656a8df4f186381a88c6ebd51e0cfdfd4c8
-  data.tar.gz: d68a4f17937165e47fe381dedade07ab625ae98c426a30c6cf09d806a2b77466
+  metadata.gz: cd30deb9f9246b10264f5e9af3a35c279ffee1c0766947b47d52c4deaf00a608
+  data.tar.gz: a544d9b97ecca711bd66dc6ecf9325d3110601b6bbaa2b7a499ffda152be4916
 SHA512:
-  metadata.gz: 439357c8e138db02f373cdefedbcd3abd79e16aa5997a8140449327352e0efbdb436b293989b0a19086fcbe41a07c09e7743a3e68b9945cd885080e31b06f056
-  data.tar.gz: 2ca4a1333cd8f21fc07deb995f2ab31b62ada7a8b95286f050bb3f481adbddf85471df28be2c80b5a838c0a91d0e770dbf144830f1349298157161284d545a6f
+  metadata.gz: 63dd6436e43358e1e59ba11277c470f37880745f7033001c8776d427d2656827007fe4a231551466bcf9328de3532ef04c621b324ccce14dfe253c7e91a93c62
+  data.tar.gz: 81e2c263b3785429f79ac9df991ecb6c19517620efd6351cafcba13450a7691ed3415545825e0c488a635ea8478099224fc05de383ff5f2d45ce9c6069ead2af

data/AGENTS.md

@@ -0,0 +1,42 @@
+## Technical
+
+- written in Ruby
+- Tests with RSpec, execute `rspec` to run them
+- Code-Style is checked with RuboCop, run `rubocop` to check
+
+## Ideas
+
+The project is a CLI that collects time-tracking information into entries and allows to show them.
+The data-backend is either the data of gtimelog or of a dialy note in Obsidian.md
+
+### gtimelog
+
+gtimelog is a GTK GUI app, that uses a single file to store when a task has ended.
+
+This allows to infer the duration of tasks by reading mulitple lines.
+
+### Obsidian.md
+
+Obsidian.md (mostly called obsidian) is a note-taking application allows to have daily notes in markdown-format.
+
+The plugin 'dayplanner' adds a special section to daily notes that are time-tracking entries. They are grouped under a headline and formatted like this
+
+```markdown
+- 10:00 - 11:00 Task 17: Hard work, Analysis, Feedback -- work client mail
+```
+
+This describes a time-entry from 10:00 to 11:00 o'clock. The entry's ticket is "Task 17" and its description is "Hard work, Analysis, Feedback". The entry is tagged with "work", "client" and "mail"
+
+## Development-Workflow
+
+- Always write a spec first
+- The spec should define the desired state
+- The spec should be failing at first
+- Then add the implementation
+- The spec should now be successful
+- The whole spec-suite should also still be without errors
+- run `rspec` to ensure that
+- if any spec fails, fix the new implementation until all specs pass
+- Lastly, run `rubocop` to ensure the code-style is good.
+- verify completeness by running `rspec` and `rubocop`.
+- Propose a commit-message, summarizing the need for the change

data/PLAN-ADD-COMMAND.md

@@ -0,0 +1,140 @@
+# Plan: `add`-command with Obsidian/Operon as datasource
+
+Collected ideas and findings for a later planning session. Nothing here is
+implemented yet.
+
+## 1. Current state
+
+- **Decision:** with Obsidian/Operon as datasource, `add` stays disabled for now.
+- **`add` crashes with both backends today.** `Command::Add#execute` calls
+  `backend.add(entry)` (`lib/ptimelog/command/add.rb:28`). Neither
+  `Ptimelog::Operon` nor `Ptimelog::Timelog` defines `add`; the timelog
+  version is commented out (`lib/ptimelog/timelog.rb:50`). So `ptimelog add …`
+  reaches `previous_entry`, then fails with `NoMethodError`.
+- **Already built and committed:** `Operon#previous_entry`
+  (`lib/ptimelog/operon.rb:44`). It returns the running timer's start, else the
+  end of the day's last session, else `operon_start_time` (default `08:00`).
+  The entry is hidden (`start **`) and has specs.
+- **README** already states that `add` is not available for the Obsidian
+  datasource.
+- **Tests:** the general-flow spec in `spec/ptimelog/command/add_spec.rb` is
+  commented out, and the `with obsidian+operon as backend` context is empty.
+
+## 2. Hard limits from the Operon docs
+
+1. **`trackers`, `duration` and `activeTracker` belong to Operon.** They can be
+   read, but should not be edited by hand (`DOCS-012:92-117`). `add` cannot
+   write tracked time.
+2. **`datetimeStart` and `datetimeEnd` are user-settable fields**
+   (`DOCS-012:70-71`). They describe a *planned* block — the only safe thing
+   `add` could write.
+3. **ptimelog only reads tracked time** (deliberate decision). A planned block
+   written by `add` does not show up in `ptimelog show` until **Log as
+   tracked** is pressed in Operon. The flow is always two steps.
+4. **`{{operonId}}` resolves on its own.** A probe showed Operon replaces a
+   literal `{{operonId:: {{operonId}}}}` shortly after the line appears,
+   without a restart. ptimelog never has to mint ids. Should it ever be needed:
+   ids are 7 characters of `[a-z0-9]` (`DOCS-015`), e.g.
+   `SecureRandom.random_number(36**7).to_s(36).rjust(7, '0')`.
+5. **Other template variables are unproven** on a line ptimelog writes
+   (`{{date}}`, `{{status}}`, `{{priority}}`, see `DOCS-061`). Write literal
+   values for those.
+
+## 3. Shape of a written line
+
+```markdown
+- [ ] <description> {{operonId:: {{operonId}}}} {{ticket:: …}} {{ptimelog:: …}} {{datetimeStart:: YYYY-MM-DDTHH:MM:00}} {{datetimeEnd:: …}} {{dateScheduled:: YYYY-MM-DD}}
+```
+
+- **Start:** `previous_entry.finish_time`. **End:** the parsed time or offset;
+  `parse_task` in `add.rb` already handles `-5`, `+5` and `HH:MM`.
+- **`dateScheduled`:** matches the Operon setting
+  `inlineTaskDailyNoteAddScheduledDate: true` and makes the task show under
+  `## Heute geplant`.
+- **Appending:** add the line as plain text so nothing else in the note moves.
+  Do not rewrite the note through a markdown parser; the old dayplanner adapter
+  had escaping trouble with `[`, `]`, `#`, `_` and `-`.
+
+## 4. Where the line goes
+
+Operon's Task Router (`DOCS-136:26-38`) offers five destinations: Daily Notes,
+Weekly Notes, Specific File, Active File, Ask Every Time. A CLI can only serve
+**Daily Notes** and **Specific File**. Operon has no "inbox" concept; Specific
+File *is* the inbox.
+
+Current local setup:
+
+- **Operon** (`.obsidian/plugins/operon/data.json → ui.taskCreationProfile`,
+  version 3): `specific-file`, pointing at `Operon/Tasks/Operon Inbox.md`, with
+  heading keyword `Heute neu`.
+- **Obsidian Core daily notes** (`.obsidian/daily-notes.json`): folder `daily`,
+  format `YYYY-MM-DD`, template `intern/Templates/Daily Note.md`. The template
+  has no tokens, so creating a missing note is a plain copy.
+
+Placement depends on the destination:
+
+| Destination   | Line lands                                                                 |
+|---------------|----------------------------------------------------------------------------|
+| Daily Notes   | under the first heading containing `Heute neu`; `##` created if missing    |
+| Specific File | under a date heading like `## [[2026-10-08]]`; the Inbox already uses them |
+
+Missing daily notes (`DOCS-137:56-64`): Operon creates them from the template;
+with `createDailyNotesAsOperonTask` on, the note becomes the task's parent. That
+setting is currently off.
+
+## 5. Design options
+
+Proposed config: `operon_task_add_location` with the values `"daily"`, an
+absolute path, or `false` (default, disables `add`).
+
+Three ways to determine the destination:
+
+- **A. Read Operon's own settings** (`data.json` plus `daily-notes.json`)
+  - Pro: never drifts from what Operon's Task Creator does.
+  - Con: depends on Operon's private plugin data. It is versioned, its mode
+    values are undocumented, and it is not a published contract
+    (`DOCS-044`, `DOCS-046`).
+- **B. Own ptimelog key**, reading only Core's `daily-notes.json` for the daily
+  folder and format (earlier recommendation)
+  - Pro: small, explicit, owned by ptimelog.
+  - Con: repeats a setting Operon already has, so the two can disagree.
+- **C. Delegate to `operon-cli`** (`operon task create`, `DOCS-127`)
+  - Pro: the supported route, with preview, verified writes and parent linking.
+  - Con: not installed here, needs Obsidian running plus the official Obsidian
+    CLI, native Linux is "public beta", and the local Obsidian is a flatpak.
+    A dead end for now.
+
+## 6. Open questions
+
+1. **Is `add` worth it at all,** given its output is invisible to `show` until
+   tracked in Operon? The alternative is capturing directly in Operon.
+2. **Destination:** A, B or C. Should `"daily"` follow Core's
+   `daily-notes.json` or a ptimelog-owned folder?
+3. **Missing note:** create it (from the template for daily notes, empty for a
+   specific file) or refuse with a hint?
+4. **Dry run:** add `add --dry-run` that prints the line without writing
+   (about 3 lines; `confirm` already has `-n`)?
+5. **Concurrent writes:** if Obsidian has the note open, its next save can
+   overwrite ptimelog's line. Accept the risk, or document "close Obsidian
+   first"?
+
+## 7. Verification procedure
+
+1. **Specs first:** exactly one line appended; the rest of the note stays
+   byte-identical; the line reads back with the same fields; start equals
+   `previous_entry`; `show` does **not** list it.
+2. **Dry run:** prints the exact line and writes nothing.
+3. **Real write with Obsidian closed:** back up the note, run `add`. `show`
+   must be unchanged. In Obsidian the task gets a real id and appears on the
+   Calendar. After **Log as tracked**, `show` has exactly one new entry with
+   matching times. Restore the note.
+4. **Regression check:** the session-parity check against
+   `~/Obsidian/Things/export-operon-time` still matches (37/37 sessions over
+   11 days at the time of writing).
+
+## 8. Possible small step before the full design
+
+Today "disabled" means a `NoMethodError`. A one-method `Operon#add` raising a
+`Ptimelog::Error` ("adding entries is not supported for the Obsidian
+datasource") would turn that into a clear message — same pattern as
+`Operon::VaultNotFound`, with one spec.

data/README.md

@@ -1,6 +1,6 @@
 # pTimeLog
 
-small tooling to transfer timelog-entries from gtimelog's timelog.txt to the PuzzleTime TimeTracking Website.
+small tooling to transfer timelog-entries from gtimelog's timelog.txt or the tasks of an Obsidian vault to the PuzzleTime time-tracking web-application.
 
 ## Approach
 
@@ -18,14 +18,15 @@ small tooling to transfer timelog-entries from gtimelog's timelog.txt to the Puz
   - [x] support user-supplied ticket-parsers
   - [x] get ticket-parser from tags
 - [x] merge equal adjacent entries into one
+- [x] caculate, show and upload durations
 - [ ] complete login/entry automation
   - [ ] handle authentication
     - [ ] login and store cookie (https://stackoverflow.com/questions/12399087/curl-to-access-a-page-that-requires-a-login-from-a-different-page#12399176)
     - [ ] send user and pwd with every request
   - [ ] make entries
   - [ ] open day in browser for review
-- [ ] avoid duplicate entries
-  - [ ] start/end time as indicator?
+- [x] avoid duplicate entries
+  - [x] start/end time as indicator?
 - [x] offer rounding times to the next 5, 10 or 15 minutes
 - [x] allow to add entries from the command-line
 - [ ] handle time-account and billable better
@@ -38,8 +39,17 @@ small tooling to transfer timelog-entries from gtimelog's timelog.txt to the Puz
   - [ ] allow to have a list of "favourite" time-accounts
   - [ ] select best-matching time-account according to tags, possibly limited to the favourites
   - [x] combine billable and account-lookup into one script
-- [ ] add cli-help
-  - [ ] use commander for CLI?
+- [x] add cli-help
+  - [x] use ~~commander~~ _cmd_parse_ for CLI
+- [x] support Obsidian as datasource
+  - [x] with explicit config
+  - [x] with reading the config from the Obsidian Vault
+  - [x] time-entries from the sessions Operon tracked on its tasks
+  - [ ] time-account/billable/metadata lookup from a note
+  - [x] support show-command: output the entries of a day
+  - [x] support upload-command: send the entries of a day to ptime
+  - [ ] support add-command: add a new entry to the current day
+  - [ ] support "last"-day for obsidian
 
 ## Installation
 
@@ -51,35 +61,88 @@ Install it with:
 
     $ ptimelog ACTION DATE
 
+Maybe it's best to explore the commands with `ptimelog help` and going from
+there.
+
 ### Actions
 
 Currently supported actions are
 
 - show
 - upload
+- confirm
 - edit
+- add
+- version
+- help
+- info
 
 ### Date-Identifier
 
-To handle a specific date, the format YYYY-MM-DD is expected, e.g. 2017-12-25. Please note that you should not work on that day, unless you bring presents.
+To handle a specific date, the format YYYY-MM-DD is expected, e.g. 2017-12-25.
+Please note that you should not work on that day, unless you bring presents or
+release a new version of Ruby.
 
 For reusability in a shell-history the following keywords are supported:
 
 - today
 - yesterday
-- last
 - all
 
-If nothing is specified, the action is applied to entries of the last day.
+Currently, you need to pass a day. The previously exisiting "last" worked fine
+to timelog.txt, but not for Obsidian.
 
 ### Edit-Identifier
 
-When the action is "edit", the next argument is treated as script that should be edited.
+When the action is "edit", the next argument is treated as script that should
+be edited.
 
 If nothing is passed, the main timelog.txt is loaded.
+:warn: The Obsidian-Datasource has no single file, because an entry can
+come from any note of the vault. Without an argument, this command only
+edits an inferer-script, which is the thing that can still be edited.
 
 Otherwise, a script to determine the time-account is loaded.
 
+
+### Adding entries
+
+In order to add entries with the ptimelog-cli, the complete entry needs to be
+quoted on the command-line to count as one argument.
+
+    $ ptimelog add 'ticket 1337: Implement requirements -- client coding'
+
+While this requires some knowledge of the file-format, it is no different than
+entering the same string in gTimelog. For now, the entry is added to the
+timelog.txt as it is passed. By default, the date/time added to the entry is
+the one when the command is executed.
+
+You can prefix a positive or negative signed number to slightly skew the entry
+(think: '-5 meeting' or '+5 lunch \*\*') or even set a precise time ('10:30
+meeting').
+
+    $ ptimelog add '-5 meeting: Discuss requirements -- client planning'
+
+:warn: Not available for the Obsidian-Datasource. Tracked time belongs to
+a task in Operon, and only Operon may write it.
+
+### Showing the Version
+
+I got tired of asking rubygems which version I installed, so I took on the
+herculean task of letting ptimelog show its own version. With the switch to a
+cmd_parse-based CLI, this has been partially offloaded to cmd_parse. You can
+imagine the weight that has been lifted off my shoulders.
+
+### Formatting the Output
+
+In order to format the output of the show-action into a table, a hopefully
+convienient field-marker has been chosen. After 0.10.0, I switched from '∴' to
+'|', which is much more widely used, but also much easier to find on keyboard.
+This removes one need to copy an unusual separator, maybe even using the mouse...
+Anyway, you can pipe the output into `column`:
+
+    ptimelog show today | column -t -s'|'
+
 ## Helper-Scripts
 
 ptimelog can prefill the account-number and billable-state of an entry.
@@ -97,13 +160,56 @@ Since these scripts are called a lot, it is better to write them in a compiled
 language. If you only like ruby, take a look at crystal. For such simple
 scripts, the code is almost identical and "just" needs to be compiled.
 
+## Operon
+
+With `obsidian: true`, entries are read from the time-sessions
+[Operon](https://github.com/hasanyilmaz/operon) tracked on the tasks of your
+vault. Operon stores them on the task itself, so one entry comes from one
+session, not from one task:
+
+    {{trackers:: 2026-10-07T11:00:00/2026-10-07T12:00:00; 2026-10-07T14:00:00/2026-10-07T15:00:00}}
+
+Only tracked time is read. A running timer and a planned block
+(`datetimeStart`/`datetimeEnd`) are no time yet, so they are skipped. A
+session counts on the day it started on. Notes below `archive/` and Operons
+own documentation are skipped.
+
+Ticket and account-tags come from two custom keys, which you can create in
+**Settings → Operon → Core → Custom Keys**:
+
+    - [ ] HIT-12345: Zeug machen {{operonId:: …}} {{ticket:: HIT-12345}} {{ptimelog:: hit sac mv}}
+
+`ticket` is the text puzzletime is asked for. `ptimelog` is a single,
+space-separated string of tags, identical to what the dayplanner-entries used
+to carry after their `--`. The first tag selects the inferer-script, the rest
+are passed to it. A task without that key is still listed, but has no account.
+
+If your vault already uses other names for these keys, map them with
+`operon_custom_keys`. A key you leave out keeps its default:
+
+    operon_custom_keys:
+      ticket: issue
+      inferer: account
+
 ## Configuration
 
 A config-file is read from `$HOME/.config/ptimelog/config`. It is expected
 to be a YAML-file. Currently, it supports the following keys:
 
-	- rounding: [integer or false, default 15]
-	- base_url: [url to your puzzletime-installation, default https://time.puzzle.ch]
+  - rounding: [integer or false, default 15]
+  - base_url: [url to your puzzletime-installation, default https://time.puzzle.ch]
+  - obsidian: [boolean, default false, read from an Obsidian vault instead of timelog.txt]
+  - obsidian_vault: [path to that vault, default ~/path/to/obsidian-vault]
+  - operon_custom_keys: [hash, default { ticket: ticket, inferer: ptimelog }, names of the keys Operon stores ticket and tags in]
+
+If the default path of `obsidian_vault` works for you, I really want to talk to
+you :-)
+
+Operons tracked time is stored to the second, so set `rounding: false` to keep
+it exact.
+
+It might still work with the timelog.txt-config. I do not use it anymore, but
+I do not want to break things needlessly. So I left it in.
 
 ## Development
 
@@ -122,7 +228,6 @@ git commits and tags, and push the `.gem` file to
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kronn/ptimelog.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/exe/ptimelog

@@ -1,6 +1,30 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative '../lib/ptimelog'
+require 'cmdparse'
+require 'ptimelog'
 
-Ptimelog::App.new(ARGV).run
+parser = CmdParse::CommandParser.new(handle_exceptions: true)
+parser.main_options.version = Ptimelog::VERSION
+parser.main_options.program_name = 'ptimelog'
+parser.main_options.banner = Ptimelog::BANNER
+
+parser.add_command(CmdParse::VersionCommand.new)
+parser.add_command(CmdParse::HelpCommand.new, default: true)
+parser.add_command(Ptimelog::Command::Info.new)
+
+parser.add_command(Ptimelog::Command::Add.new)
+parser.add_command(Ptimelog::Command::Edit.new)
+parser.add_command(Ptimelog::Command::Show.new)
+parser.add_command(Ptimelog::Command::Upload.new)
+parser.add_command(Ptimelog::Command::Confirm.new)
+
+begin
+  parser.parse
+rescue Ptimelog::Error => e
+  warn <<~MSG
+    An Error occured: #{e.class}
+
+    #{e.message}
+  MSG
+end

data/lib/ptimelog/command/add.rb

@@ -5,25 +5,64 @@ require 'pathname'
 module Ptimelog
   module Command
     # add a new entrie with the current date and time
-    class Add < Base
-      def initialize(task)
-        super()
+    class Add < CmdParse::Command
+      def initialize
+        super('add', takes_commands: false)
 
-        @task = task
-        @timelog = Ptimelog::Timelog.instance
+        @data_source = DataSource.new(
+          Configuration.instance,
+          NamedDate.new.named_date('today')
+        )
+
+        options.on('--debug', 'Show debugging output') { @debug = true }
       end
 
-      def needs_entries?
-        false
+      def execute(task_line)
+        start = backend.previous_entry.finish_time
+        finish, task = parse_task(task_line)
+        ticket, desc = task.split(':', 2)
+
+        entry = create_entry(start, finish, ticket, desc)
+        debug(entry.to_s)
+
+        backend.add(entry)
       end
 
-      def run
-        date_time = Time.now.strftime('%F %R')
+      private
+
+      def parse_task(line)
+        matches = line.match('(?<time>\d{1,2}:\d{2} )?(?<offset>[+-]\d+ )?(?<task>.*)')
+        formatted_time = if matches[:time]
+                           Time.parse(matches[:time])
+                         else
+                           Time.now
+                         end
+                         .localtime
+                         .then { |time| time + (matches[:offset].to_i * 60) }
+                         .strftime('%R')
+
+        [formatted_time, matches[:task]]
+      end
 
-        @timelog.timelog_txt.open('a') do |log|
-          log << "#{date_time}: #{@task}\n"
+      def create_entry(start, finish, ticket, desc)
+        Entry.new.tap do |e|
+          e.date = Date.today
+          e.start_time = start
+          e.finish_time = finish
+          e.ticket = ticket
+          e.description = desc
         end
       end
+
+      def backend
+        @data_source.backend
+      end
+
+      def debug(msg)
+        return unless @debug
+
+        warn msg
+      end
     end
   end
 end

data/lib/ptimelog/command/confirm.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ptimelog
+  module Command
+    # show entries of one day or all of them
+    class Confirm < CmdParse::Command
+      attr_reader :entries
+
+      def initialize
+        super('confirm', takes_commands: false)
+        @durations = false
+        @dry_run = false
+        @entries = {}
+        @config = Configuration.instance
+
+        options.on('-d', '--durations', 'Summarize durations by ticket') { @durations = true }
+        options.on('-n', '--dry-run', 'Do not execute, just dry-run') { @dry_run = true }
+      end
+
+      def execute(maybe_named_day) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+        @day = Ptimelog::NamedDate.new.named_date(maybe_named_day)
+        @entries = Ptimelog::DataSource.new(@config, @day).entries
+
+        @entries.each do |date, list|
+          next if list.empty?
+
+          valids = Ptimelog::Joiner.new(compact_on_ticket_only: @durations).join_similar(
+            list.select(&:valid?).sort_by { |entry| entry.ticket.to_s }
+          ).sort_by(&:start_time)
+          total_duration = duration(valids.sum(&:duration))
+
+          output(date, valids, total_duration)
+
+          upload(date) if ask('Upload this day? [Yn]', 'y').downcase == 'y'
+        end
+      end
+
+      private
+
+      def output(date, entries, total_duration)
+        puts date,
+             '----------'
+
+        entries.each do |entry|
+          puts entry
+        end
+
+        puts '----------',
+             "Total work done: #{total_duration} hours",
+             '----------------------------',
+             nil
+      end
+
+      def ask(question, default = nil)
+        puts question
+
+        answer = $stdin.gets.chomp.strip
+
+        if answer.empty?
+          raise 'No answer and no default given' if default.nil?
+
+          default
+        else
+          answer
+        end
+      end
+
+      def upload(date)
+        options = @durations ? '-d' : ''
+        cmd = "#{$PROGRAM_NAME} upload #{date} #{options}"
+
+        if @dry_run
+          puts cmd
+        else
+          system(cmd)
+        end
+      end
+
+      def duration(durations) = Time.at(durations).utc.strftime('%H:%M')
+    end
+  end
+end

data/lib/ptimelog/command/edit.rb

@@ -4,20 +4,46 @@ module Ptimelog
   module Command
     # edit one file. without argument, it will edit the timelog, otherwise a
     # parser-script is loaded
-    class Edit < Base
-      def initialize(file)
-        super()
+    class Edit < CmdParse::Command
+      def initialize
+        super('edit', takes_commands: false)
 
+        options.on('--init', 'Add a starting template') do
+          @init_content = <<~BASH
+            #!/usr/bin/env bash
+            set -euo pipefail
+            IFS=$'\n\t'
+
+            echo "0" # this is the ID
+            echo "false" # true/false for billable
+            echo "true" # true/false for publishable
+          BASH
+        end
+
+        @config = Configuration.instance
         @scripts = Script.new(@config[:dir])
-        @file    = file
       end
 
-      def run
-        launch_editor(find_file(@file))
+      def execute(file = nil)
+        target = find_file(file)
+
+        return puts(no_file_hint) if target.is_a?(NullPathname)
+
+        launch_editor(target)
       end
 
       private
 
+      def no_file_hint
+        <<~MSG
+          No file to edit.
+
+          An entry can come from any note of the vault, so the Obsidian-Datasource
+          has no single file. Pass the name of an inferer-script instead,
+          e.g. 'ptimelog edit hit'.
+        MSG
+      end
+
       def launch_editor(file)
         editor = `which $EDITOR`.chomp
 
@@ -28,6 +54,7 @@ module Ptimelog
         %i[
           timelog
           existing_inferer
+          prefilled_inferer
           empty_inferer
         ].each do |file_lookup|
           valid, filename = send(file_lookup, requested_file)
@@ -37,7 +64,10 @@ module Ptimelog
       end
 
       def timelog(file)
-        [file.nil?, Timelog.timelog_txt]
+        [
+          file.nil?,
+          Ptimelog::DataSource.new(@config, Ptimelog::NamedDate.new.named_date(:today)).file,
+        ]
       end
 
       def existing_inferer(file)
@@ -46,6 +76,16 @@ module Ptimelog
         [fn.exist?, fn]
       end
 
+      def prefilled_inferer(file)
+        fn = @scripts.inferer(file)
+
+        return [false, fn] unless fn.empty? && @init_content
+
+        fn.write(@init_content)
+
+        [fn.exist?, fn]
+      end
+
       def empty_inferer(file)
         [true, @scripts.inferer(file)]
       end