bug: :bug: Logic for determining if an plan or Markdown file was created is flawed

[esacteksab]

gh-tp/cmd/tools.go

Lines 34 to 54 in 75a65e4

	// existsOrCreate checks to see if a plan file and markdown exist or were created
	// Prints to terminal stating so
	func existsOrCreated(files []tpFile) error {
	for _, v := range files {
	exists := doesExist(v.Name)
	if exists {
	Logger.Debugf("%s file %s was created.", v.Purpose, v.Name)
	fmt.Fprintf(color.Output, "%s %s%s\n",
	bold(green("✔")), v.Purpose, " Created...")
	} else if !exists {
	//
	Logger.Errorf("Markdown file %s was not created.", v.Name)
	fmt.Fprintf(color.Output, "%s %s%s\n",
	bold(red("✕")), v.Purpose, " Failed to Create ...")
	} else {
	// I'm only human. NFC how you got here. I hope to never have to find out.
	Logger.Errorf("If you see this error message, please open a bug. Error Code: TPE003. Error: %s", err)
	}
	}
	return err
	}

existsOrCreated() is a bit misleading. "Does the file exist?" It may or may not. If it does, "Was it created? (by us?)" That's the edge case. It may not have been by us, rather it could be a remanant from a previous run or something else entirely. But we report that it was created simply because it exists.

Because of the generic nature of the file name and simply checking that the file exists as a way to say we created it, we may never know if it is fact the file we created. We need a unique identifier related to the file to have an awareness that that is in fact the file we created.

Brainstorming

• We could possibly move the logic to the planMd, err = os.Create(mdParam) so that when this is Close()'d we could do the 'File created' message there.
• We could prepend a unique ID to each file and use that as the identifier to know that that file is in fact the file we created.
• Put a UUID in a comment in the markdown and parse the UUID to identify that that file is in fact the file we created.
• Create a hash or md5sum of the file and use that to calculate that that is in fact the file we created.

[esacteksab]

A summarization from Claude talking through potential patterns and solutions.

---

File Naming Strategy: Timestamp-Based Solution

Overview

In our discussion about creating unique filenames in Go while ensuring related files share a common identifier, we explored several patterns:

1. Using os.CreateTemp for system-managed unique files
2. Using O_EXCL flag for atomically creating non-existent files
3. File locking for controlling access across processes
4. Atomic operations for safely writing/replacing files

For the specific requirement of pairing related files ("plan" and "markdown") that are created at the same time with sequential identifiers, we determined a timestamp-based approach is optimal.

Timestamp Implementation

func getSequentialID() string {
    // Format: YYYYMMDDHHmmss
    return time.Now().Format("20060102150405")
}

func createFileSet() (string, error) {
    id := getSequentialID()
    
    planFile := fmt.Sprintf("plan-%s.txt", id)
    markdownFile := fmt.Sprintf("markdown-%s.txt", id)
    
    // Create both files...
    
    return id, nil
}

For additional collision protection, a random suffix can be added:

func getSequentialID() string {
    // Format: YYYYMMDDHHmmss-XXX (XXX = random 3-digit number)
    return fmt.Sprintf("%s-%03d", 
        time.Now().Format("20060102150405"),
        rand.Intn(1000))
}

Advantages

• Naturally sequential: Files sort chronologically by default
• Zero state management: No counter files or databases needed
• Human-readable: Timestamps are easily interpreted
• Cross-process safe: Multiple processes can generate IDs without coordination
• Identifying latest: Simple sorting finds most recent files
• Unique pairings: Related files created together share the same ID

Disadvantages

• Longer identifiers: Timestamps are longer than simple incrementing numbers
• Time dependencies: Requires accurate system clock
• Non-consecutive: May have gaps if files aren't created regularly

Potential Pitfalls

• Clock skew: In distributed systems, different machines may have slightly different times
• Clock adjustments: If system time is adjusted backward, duplicates could occur
• Resolution limits: Creating multiple file sets within the same second requires additional random component
• Timezone concerns: Using local time could cause confusion; UTC is preferred
• Year 2038 problem: For 32-bit systems storing Unix timestamps (not an issue with string format)
• Sorting complications: If custom formats are used, lexicographic sorting might not match chronological order

Comparison to Alternative (Counter-Based Approach)

While a simple counter (1, 2, 3...) would provide more compact IDs, it requires maintaining state between program runs through:

• File-based persistence
• Database storage
• Distributed counter service

These all introduce additional complexity and potential failure points, making the timestamp approach preferable for most scenarios that don't require absolutely minimal ID length.