vscodepm

Documentation

Overview

Package vscodepm syncs gitmap repos into the alefragnani.project-manager VS Code extension's projects.json file.

Path resolution always discovers the VS Code USER-DATA root first, then appends the relative tail. The full path is never hardcoded; if the user has a portable VS Code install or non-standard APPDATA the resolver picks it up automatically.

See spec/01-vscode-project-manager-sync/README.md

Index

• Variables
• func DetectTags(rootPath string) []string
• func OverwritePaths(rootPath, name string, paths []string) error
• func ProjectsJSONPath() (string, error)
• func RenameByPath(rootPath, newName string) (bool, error)
• func UserDataRoot() (string, error)
• type Entry
• type Pair
• type SyncSummary
  • func Sync(pairs []Pair) (SyncSummary, error)

Variables

var ErrExtensionMissing = errors.New("project-manager extension storage dir not found")

ErrExtensionMissing is returned when projects.json's parent directory (the project-manager extension storage dir) does not exist — usually because the extension is not installed.

var ErrUserDataMissing = errors.New("vscode user-data root not found")

ErrUserDataMissing is returned when the VS Code user-data root cannot be located (env vars unset OR the directory does not exist).

Functions

func DetectTags

func DetectTags(rootPath string) []string

DetectTags inspects rootPath's top-level filesystem and returns a sorted, de-duplicated list of marker tags (e.g. "git", "node", "go"). The set is intentionally small and deterministic so projects.json diffs stay stable across runs.

Detection is shallow (top-level only) and read-only — no recursion, no network, no shelling out. Unreadable / missing rootPath returns nil so callers can treat detection as best-effort.

The returned slice respects the canonical order in constants.AutoTagOrder so two runs on the same repo always produce identical JSON output.

func OverwritePaths

func OverwritePaths(rootPath, name string, paths []string) error

OverwritePaths sets the Paths field of the entry matching rootPath to EXACTLY the supplied slice (no union). Used by `gitmap code paths rm` so removed paths actually disappear from projects.json instead of being re-merged back in by the regular Sync union semantics.

If the entry does not exist yet, it is created with the supplied paths. Other fields (Tags / Enabled / Profile) are preserved on existing rows.

func ProjectsJSONPath

func ProjectsJSONPath() (string, error)

ProjectsJSONPath returns the absolute path to projects.json by joining the discovered user-data root with the extension-relative tail. Returns ErrUserDataMissing when the root is not present, or ErrExtensionMissing when the extension storage dir is absent.

func RenameByPath

func RenameByPath(rootPath, newName string) (bool, error)

RenameByPath updates the Name field of the entry whose rootPath matches. Paths / Tags / Enabled / Profile are intentionally left alone. Returns true when an entry was actually renamed (false = no-op).

func UserDataRoot

func UserDataRoot() (string, error)

UserDataRoot returns the active VS Code user-data directory for the current OS, or ErrUserDataMissing if it cannot be located on disk.

Types

type Entry

type Entry struct {
	Name     string   `json:"name"`
	RootPath string   `json:"rootPath"`
	Paths    []string `json:"paths"`
	Tags     []string `json:"tags"`
	Enabled  bool     `json:"enabled"`
	Profile  string   `json:"profile"`
}

Entry mirrors one object in projects.json. Field order and JSON tags match the alefragnani.project-manager schema exactly so encoded files stay diff-friendly with manual edits and the sample fixture (spec/01-vscode-project-manager-sync/sample-projects.json).

type Pair

type Pair struct {
	RootPath string
	Name     string
	Paths    []string
	Tags     []string
}

Pair is one (rootPath, name, paths, tags) tuple to upsert into projects.json. Both Paths (multi-root, v3.39.0+) and Tags (auto-derived, v3.40.0+) are UNIONed with whatever the user already has on disk so gitmap never silently removes a user-added path or tag.

type SyncSummary

type SyncSummary struct {
	Added     int
	Updated   int
	Unchanged int
	Total     int
}

SyncSummary is returned from Sync to describe what changed.

func Sync

func Sync(pairs []Pair) (SyncSummary, error)

Sync reconciles projects.json with the supplied DB-side pairs.

Behavior:

• New rootPath -> append a default Entry with Paths = pair.Paths.
• Existing rootPath -> update Name. Paths becomes UNION(existing, pair.Paths). Tags / Enabled / Profile are preserved (so user edits in the VS Code UI survive untouched).
• Foreign entries (rootPath not in pairs) -> preserved verbatim.

Writes are atomic: temp file in the same directory then os.Rename. Returns ErrUserDataMissing / ErrExtensionMissing when the path cannot be resolved — callers should treat those as soft skips.