Documentation
¶
Index ¶
- Constants
- func AbsPath(ctx context.Context, relPath string) (string, error)
- func AgentTranscriptFileName(agentID string) string
- func CaseInsensitiveFS() bool
- func ClearWorktreeRootCache()
- func Equal(a, b string) bool
- func ExtractSessionIDFromTranscriptPath(transcriptPath string) string
- func GetLastTimestampFromBytes(data []byte) time.Time
- func GetLastTimestampFromFile(path string) time.Time
- func GetWorktreeID(worktreePath string) (string, error)
- func IsInfrastructurePath(path string) bool
- func IsProtectedSubpath(parent, child string) bool
- func IsRelativeTraversal(rel string) bool
- func IsSubpath(parent, child string) bool
- func ParseTimestampFromJSONL(line string) time.Time
- func SessionMetadataDirFromSessionID(sessionID string) string
- func SubagentsDir(transcriptDir, sessionID string) string
- func ToRelativePath(absPath, cwd string) string
- func WorktreeRoot(ctx context.Context) (string, error)
Constants ¶
const ( EntireDir = ".entire" EntireTmpDir = ".entire/tmp" EntireMetadataDir = ".entire/metadata" )
Directory constants
const ( PromptFileName = "prompt.txt" TranscriptFileName = "full.jsonl" TranscriptFileNameLegacy = "full.log" // CompactTranscriptFileName is the compact transcript stored alongside // full.jsonl. It holds the full compacted session; this checkpoint's slice // begins at the session metadata's compact_transcript_start. CompactTranscriptFileName = "transcript.jsonl" MetadataFileName = "metadata.json" CheckpointFileName = "checkpoint.json" ContentHashFileName = "content_hash.txt" SettingsFileName = "settings.json" // AssetsDir is the per-session subfolder holding externalized transcript // assets (e.g. images); AssetsManifestFile indexes them. AssetsDirName is the // bare tree-entry name (no trailing slash) used when walking git trees. AssetsDirName = "assets" AssetsDir = "assets/" AssetsManifestFile = "assets/manifest.json" )
Metadata file names
const MetadataBranchName = "entire/checkpoints/v1"
MetadataBranchName is the orphan branch used by manual-commit strategy to store metadata
const TrailsBranchName = "entire/trails/v1"
TrailsBranchName is the orphan branch used to store trail metadata. Trails are branch-centric work tracking abstractions that link to checkpoints by branch name.
Variables ¶
This section is empty.
Functions ¶
func AbsPath ¶
AbsPath returns the absolute path for a relative path within the repository. If the path is already absolute, it is returned as-is. Uses WorktreeRoot() to resolve paths relative to the worktree root.
func AgentTranscriptFileName ¶ added in v0.10.0
AgentTranscriptFileName returns the file name an agent writes a subagent's transcript under: agent-<agentID>.jsonl.
func CaseInsensitiveFS ¶ added in v0.9.0
func CaseInsensitiveFS() bool
CaseInsensitiveFS reports whether path comparisons should be case-insensitive on the host OS. This is OS-based, not volume-based: Windows and macOS default to case-insensitive filesystems, Linux to case-sensitive. Keying on GOOS keeps the result deterministic. It must only influence EXCLUSION decisions (see IsProtectedSubpath / Equal): on an atypical volume (e.g. a case-sensitive macOS APFS volume) it treats a differently-cased path as matching, which is safe only when the effect is to exclude more, never to widen an allow gate.
func ClearWorktreeRootCache ¶ added in v0.4.8
func ClearWorktreeRootCache()
ClearWorktreeRootCache clears the cached worktree root. This is primarily useful for testing when changing directories.
func Equal ¶ added in v0.9.0
Equal reports whether two paths refer to the same location, honoring the host OS's case sensitivity (see CaseInsensitiveFS). Both inputs are cleaned and slash-normalized before comparison. Like IsProtectedSubpath, this is intended for EXCLUSION matching (e.g. protected files), not fail-closed containment.
func ExtractSessionIDFromTranscriptPath ¶
ExtractSessionIDFromTranscriptPath attempts to extract a session ID from a transcript path. Claude transcripts are stored at ~/.claude/projects/<project>/sessions/<id>.jsonl If the path doesn't match expected format, returns empty string.
func GetLastTimestampFromBytes ¶
GetLastTimestampFromBytes extracts the timestamp from the last non-empty line of JSONL content. Returns zero time if not found.
func GetLastTimestampFromFile ¶
GetLastTimestampFromFile reads the last non-empty line from a JSONL file and extracts the timestamp field. Returns zero time if file doesn't exist or no valid timestamp is found.
func GetWorktreeID ¶
GetWorktreeID returns the internal git worktree identifier for the given path. For the main worktree (where .git is a directory), returns empty string. For linked worktrees (where .git is a file), extracts the name from .git/worktrees/<name>/ path. This name is stable across `git worktree move`.
func IsInfrastructurePath ¶
IsInfrastructurePath returns true if the path is part of CLI infrastructure (i.e., inside the .entire directory). It is used only to EXCLUDE infra paths from checkpoints/tracking, so it matches case-insensitively on case-insensitive filesystems via IsProtectedSubpath. Do not use it as a containment/allow gate.
func IsProtectedSubpath ¶ added in v0.9.0
IsProtectedSubpath reports whether child is under parent for the purpose of EXCLUDING protected/infrastructure content from checkpoints and tracking. Unlike IsSubpath it honors OS case-insensitivity (see CaseInsensitiveFS), so a case variant of a protected dir (".Claude" vs ".claude") is still excluded on Windows/macOS.
SECURITY: never use this for allow/containment decisions. Case-folding widens what counts as "inside" parent, which is safe only when the effect is to exclude more. On a case-sensitive volume under a case-insensitive GOOS it over-matches; for a fail-closed gate that would fail open. Use IsSubpath there.
func IsRelativeTraversal ¶ added in v0.7.7
IsRelativeTraversal reports whether rel escapes its base directory. It accepts both OS-native paths and Git-style slash-normalized paths.
func IsSubpath ¶ added in v0.5.1
IsSubpath reports whether child is lexically under parent (or equal to it). It uses filepath.Rel, which cleans both inputs and is traversal-resistant: a crafted child like "/a/b/../../../etc/passwd" that escapes parent will produce a relative path starting with ".." and be rejected.
Matching is case-SENSITIVE. This is the correct primitive for fail-closed containment/allow checks (e.g. validating an attacker-influenced path stays under an Entire-owned dir): on a case-sensitive volume a differently-cased path names a different directory, so folding it in would fail open. For EXCLUSION decisions that must also catch case variants on Windows/macOS, use IsProtectedSubpath instead.
func ParseTimestampFromJSONL ¶
ParseTimestampFromJSONL extracts the timestamp from a JSONL line. Returns zero time if the line is empty or doesn't contain a valid timestamp.
func SessionMetadataDirFromSessionID ¶
SessionMetadataDirFromSessionID returns the path to a session's metadata directory for the given Entire session ID. The sessionID must be the full, already date-prefixed Entire session identifier as stored on disk, not an agent-specific or raw Claude ID.
func SubagentsDir ¶ added in v0.10.0
SubagentsDir returns the directory an agent stores a session's subagent transcripts in: <transcriptDir>/<sessionID>/subagents.
This layout lives here, in the leaf paths package, because it is needed on both sides of the import graph — the lifecycle dispatcher and the strategy, review, and agentimport packages all resolve it, and those cannot import each other. Before it was named it existed as five copies of the same filepath.Join, which is how the SubagentEnd path came to disagree with the turn-end path about where subagent transcripts live.
sessionID is the *agent's* session ID (the transcript file's own basename), not the date-prefixed Entire session ID.
func ToRelativePath ¶
ToRelativePath converts an absolute path to relative. Returns empty string if the path is outside the working directory.
func WorktreeRoot ¶ added in v0.4.8
WorktreeRoot returns the git worktree root directory. Uses 'git rev-parse --show-toplevel' which returns the working tree toplevel. In a worktree this is the worktree root, not the main repository root. The result is cached per working directory. Returns an error if not inside a git repository.
Types ¶
This section is empty.
Source Files