beads/cmd/bd/export_auto.go
Kevin Glynn 8518e71d66
feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393)
* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping

Follow-up to #3368 as discussed with @maphew. Adds the envelope format
that wraps all --json output as {"schema_version": N, "data": <payload>},
gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers.

Legacy mode (default): unchanged behavior from #3368 — objects get
schema_version injected inline, arrays pass through raw.

Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types.
The original payload is untouched inside .data — no type corruption,
no field injection. A one-time deprecation notice is emitted to stderr
when --json is used without the env var.

Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0
as a temporary escape hatch for one release cycle.

Includes:
- wrapWithSchemaVersion dual-mode logic
- outputJSONError and buildJSONError envelope support
- Deprecation notice on stderr (once per process)
- Tests for both legacy and envelope modes
- Migration guide in docs/JSON_SCHEMA.md

* fix: suppress deprecation notice when stderr is not a TTY

Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the
"NOTE: bd --json output format will change in v2.0" message only
appears in interactive terminals. Test harnesses and pipelines
capture stderr via CombinedOutput(), and the trailing notice after
the JSON closing brace caused json.Unmarshal to fail with
"invalid character 'N' after top-level value" in 15 CI tests.

Follows the same TTY-gating pattern used by ShouldUseColor and
ShouldUseEmoji.

* fix: suppress gosec G304 false positive in hookWorkTreeRoot

The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a
well-known git internal file from a trusted environment variable set by
git itself during hook execution. Not a user-controlled file inclusion.

This false positive causes the Lint CI check to fail on every PR in
the repo, masking real lint issues.
2026-04-21 13:24:17 -07:00

409 lines
13 KiB
Go

package main
import (
"context"
"encoding/json"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"time"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/types"
)
// exportAutoState tracks auto-export state to avoid redundant work.
type exportAutoState struct {
LastDoltCommit string `json:"last_dolt_commit"`
Timestamp time.Time `json:"timestamp"`
Issues int `json:"issues"`
Memories int `json:"memories"`
}
const exportAutoStateFile = "export-state.json"
// maybeAutoExport writes a git-tracked JSONL file if enabled and due.
// Called from PersistentPostRun after auto-backup.
func maybeAutoExport(ctx context.Context) {
// Skip when running as a git hook to avoid re-export during pre-commit.
if os.Getenv("BD_GIT_HOOK") == "1" {
debug.Logf("auto-export: skipping — running as git hook\n")
return
}
if !config.GetBool("export.auto") {
return
}
if store == nil {
return
}
if lm, ok := storage.UnwrapStore(store).(storage.LifecycleManager); ok && lm.IsClosed() {
return
}
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return
}
// Load state and check throttle
state := loadExportAutoState(beadsDir)
interval := config.GetDuration("export.interval")
if interval == 0 {
interval = 60 * time.Second
}
if !state.Timestamp.IsZero() && time.Since(state.Timestamp) < interval {
debug.Logf("auto-export: throttled (last export %s ago, interval %s)\n",
time.Since(state.Timestamp).Round(time.Second), interval)
return
}
// Change detection via Dolt commit hash
currentCommit, err := store.GetCurrentCommit(ctx)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: auto-export skipped: failed to get current commit: %v\n", err)
return
}
if currentCommit == state.LastDoltCommit && state.LastDoltCommit != "" {
debug.Logf("auto-export: no changes since last export\n")
return
}
// Determine output path
exportPath := config.GetString("export.path")
if exportPath == "" {
if globalFlag {
exportPath = "global-issues.jsonl"
} else {
exportPath = "issues.jsonl"
}
}
fullPath := filepath.Join(beadsDir, exportPath)
// Run the export
issueCount, memoryCount, err := exportToFile(ctx, fullPath, true)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: auto-export failed: %v\n", err)
return
}
debug.Logf("auto-export: wrote %d issues and %d memories to %s\n",
issueCount, memoryCount, fullPath)
// Don't prime the throttle on an empty export (e.g. immediately after
// `bd init`). Saving state here would block the first real `bd create`
// from exporting for up to export.interval seconds even though the data
// has changed. Remove the empty file too so users don't see a stale 0-byte
// issues.jsonl before any issues exist.
if issueCount == 0 && memoryCount == 0 {
_ = os.Remove(fullPath)
return
}
// Optional git add — skip when no-git-ops is set (GH#3314), when not in a
// git repo (standalone BEADS_DIR flow), or when export.git-add is false.
if config.GetBool("export.git-add") && !config.GetBool("no-git-ops") && isGitRepo() {
if err := gitAddFile(fullPath); err != nil {
fmt.Fprintf(os.Stderr, "Warning: auto-export: git add failed: %v\n", err)
}
}
// Save state
newState := exportAutoState{
LastDoltCommit: currentCommit,
Timestamp: time.Now(),
Issues: issueCount,
Memories: memoryCount,
}
saveExportAutoState(beadsDir, &newState)
}
// exportToFile exports issues + memories to the given file path.
// Used by both `bd export -o` and auto-export.
func exportToFile(ctx context.Context, path string, includeMemories bool) (issueCount, memoryCount int, err error) {
f, err := os.Create(path) //nolint:gosec // user-configured output path
if err != nil {
return 0, 0, fmt.Errorf("failed to create export file: %w", err)
}
defer f.Close()
// Build filter: exclude infra types and templates
filter := types.IssueFilter{Limit: 0}
var infraTypes []string
if store != nil {
infraSet := store.GetInfraTypes(ctx)
if len(infraSet) > 0 {
for t := range infraSet {
infraTypes = append(infraTypes, t)
}
}
}
if len(infraTypes) == 0 {
infraTypes = dolt.DefaultInfraTypes()
}
for _, t := range infraTypes {
filter.ExcludeTypes = append(filter.ExcludeTypes, types.IssueType(t))
}
isTemplate := false
filter.IsTemplate = &isTemplate
// Fetch issues
issues, err := store.SearchIssues(ctx, "", filter)
if err != nil {
return 0, 0, fmt.Errorf("failed to search issues: %w", err)
}
// Also fetch wisps
ephemeral := true
wispFilter := filter
wispFilter.Ephemeral = &ephemeral
wispIssues, err := store.SearchIssues(ctx, "", wispFilter)
if err == nil && len(wispIssues) > 0 {
issues = append(issues, wispIssues...)
}
// Bulk-load relational data
if len(issues) > 0 {
issueIDs := make([]string, len(issues))
for i, issue := range issues {
issueIDs[i] = issue.ID
}
labelsMap, _ := store.GetLabelsForIssues(ctx, issueIDs)
allDeps, _ := store.GetDependencyRecordsForIssues(ctx, issueIDs)
commentsMap, _ := store.GetCommentsForIssues(ctx, issueIDs)
commentCounts, _ := store.GetCommentCounts(ctx, issueIDs)
depCounts, _ := store.GetDependencyCounts(ctx, issueIDs)
for _, issue := range issues {
issue.Labels = labelsMap[issue.ID]
issue.Dependencies = allDeps[issue.ID]
issue.Comments = commentsMap[issue.ID]
}
// Write issues
enc := json.NewEncoder(f)
for _, issue := range issues {
counts := depCounts[issue.ID]
if counts == nil {
counts = &types.DependencyCounts{}
}
sanitizeZeroTime(issue)
record := &exportIssueRecord{
RecordType: "issue",
IssueWithCounts: &types.IssueWithCounts{
Issue: issue,
DependencyCount: counts.DependencyCount,
DependentCount: counts.DependentCount,
CommentCount: commentCounts[issue.ID],
},
}
if err := enc.Encode(record); err != nil {
return 0, 0, fmt.Errorf("failed to write issue %s: %w", issue.ID, err)
}
issueCount++
}
}
// Write memories
if includeMemories {
allConfig, err := store.GetAllConfig(ctx)
if err == nil {
fullPrefix := kvPrefix + memoryPrefix
for k, v := range allConfig {
if !strings.HasPrefix(k, fullPrefix) {
continue
}
userKey := strings.TrimPrefix(k, fullPrefix)
record := map[string]string{
"_type": "memory",
"key": userKey,
"value": v,
}
data, err := json.Marshal(record)
if err != nil {
continue
}
if _, err := f.Write(data); err != nil {
return issueCount, memoryCount, fmt.Errorf("failed to write memory: %w", err)
}
if _, err := f.Write([]byte{'\n'}); err != nil {
return issueCount, memoryCount, fmt.Errorf("failed to write newline: %w", err)
}
memoryCount++
}
}
}
if err := f.Sync(); err != nil {
return issueCount, memoryCount, fmt.Errorf("failed to sync: %w", err)
}
return issueCount, memoryCount, nil
}
func loadExportAutoState(beadsDir string) *exportAutoState {
path := filepath.Join(beadsDir, exportAutoStateFile)
data, err := os.ReadFile(path) //nolint:gosec
if err != nil {
return &exportAutoState{}
}
var state exportAutoState
if err := json.Unmarshal(data, &state); err != nil {
return &exportAutoState{}
}
return &state
}
func saveExportAutoState(beadsDir string, state *exportAutoState) {
path := filepath.Join(beadsDir, exportAutoStateFile)
data, err := json.Marshal(state)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: auto-export: failed to marshal state: %v\n", err)
return
}
if err := os.WriteFile(path, data, 0o600); err != nil {
fmt.Fprintf(os.Stderr, "Warning: auto-export: failed to save state: %v\n", err)
}
}
// gitAddFile stages a file in the enclosing git repo. When called from
// inside a git hook, it scrubs inherited GIT_* env vars (so git
// rediscovers the repo from cwd rather than treating cmd.Dir as the
// worktree root) and skips staging when the target is outside the hook's
// worktree (the .beads/redirect case, where staging would pollute the
// main repo's index). See GH#3311, scrubGitHookEnv, hookWorkTreeRoot.
func gitAddFile(path string) error {
if wt := hookWorkTreeRoot(); wt != "" && !pathInsideDir(path, wt) {
// Running inside a hook AND target is outside the hook's worktree.
// Staging here would pollute a different repo's index; skip.
return nil
}
cmd := exec.Command("git", "add", path)
cmd.Dir = filepath.Dir(path)
cmd.Env = scrubGitHookEnv(os.Environ())
return cmd.Run()
}
// scrubGitHookEnv returns env with the GIT_* variables that can poison
// git's repo/worktree auto-discovery or object-store resolution removed,
// so git falls back to auto-discovery from cwd. The scrub is
// unconditional: if a user has intentionally exported any of these vars
// for scripting purposes, they will be stripped from the git-add child
// process. That is the correct trade-off here; we never want beads'
// auto-stage to honor a GIT_DIR pointing at an unrelated repo.
//
// Covered vars:
// - Repo/worktree discovery: GIT_DIR, GIT_WORK_TREE, GIT_COMMON_DIR,
// GIT_PREFIX, GIT_CEILING_DIRECTORIES, GIT_DISCOVERY_ACROSS_FILESYSTEM
// - Index routing: GIT_INDEX_FILE
// - Object routing: GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES
// - Config injection (any GIT_CONFIG* — e.g. GIT_CONFIG_PARAMETERS set
// when the parent ran `git -c core.worktree=… commit`): the whole
// GIT_CONFIG namespace, which includes _COUNT, _KEY_n, _VALUE_n,
// _GLOBAL, _SYSTEM, _NOSYSTEM, and the legacy GIT_CONFIG itself.
func scrubGitHookEnv(env []string) []string {
// The GIT_CONFIG prefix (no trailing "=") is intentional: it matches
// GIT_CONFIG=, GIT_CONFIG_COUNT=, GIT_CONFIG_KEY_n=, GIT_CONFIG_VALUE_n=,
// GIT_CONFIG_PARAMETERS=, GIT_CONFIG_GLOBAL=, GIT_CONFIG_SYSTEM=, and
// GIT_CONFIG_NOSYSTEM= — the whole family — in one entry. No standard
// git env var starts with GIT_CONFIG that we want to preserve.
prefixes := []string{
"GIT_DIR=",
"GIT_WORK_TREE=",
"GIT_INDEX_FILE=",
"GIT_COMMON_DIR=",
"GIT_PREFIX=",
"GIT_OBJECT_DIRECTORY=",
"GIT_ALTERNATE_OBJECT_DIRECTORIES=",
"GIT_CEILING_DIRECTORIES=",
"GIT_DISCOVERY_ACROSS_FILESYSTEM=",
"GIT_CONFIG",
}
out := make([]string, 0, len(env))
for _, e := range env {
skip := false
for _, p := range prefixes {
if strings.HasPrefix(e, p) {
skip = true
break
}
}
if !skip {
out = append(out, e)
}
}
return out
}
// hookWorkTreeRoot returns the root of the worktree whose git hook we
// are running inside, based on the inherited GIT_DIR env var. Returns ""
// when GIT_DIR is not set (the normal non-hook case) or cannot be
// resolved to a work-tree.
//
// Resolution rules:
// - In a linked worktree, GIT_DIR points at main/.git/worktrees/<name>
// and that directory contains a "gitdir" file whose contents are the
// absolute path to the worktree's .git FILE. The worktree root is
// the parent of that .git file.
// - In a non-worktree, GIT_DIR is typically ".git" or "<repo>/.git";
// the worktree root is its parent.
func hookWorkTreeRoot() string {
gitDir := os.Getenv("GIT_DIR")
if gitDir == "" {
return ""
}
var root string
if data, err := os.ReadFile(filepath.Join(gitDir, "gitdir")); err == nil { // #nosec G304 -- path is GIT_DIR/gitdir, a well-known git internal file
if dotGit := strings.TrimSpace(string(data)); dotGit != "" {
root = filepath.Dir(dotGit)
}
}
if root == "" && filepath.Base(gitDir) == ".git" {
root = filepath.Dir(gitDir)
}
if root == "" {
return ""
}
abs, err := filepath.Abs(root)
if err != nil {
return ""
}
return abs
}
// pathInsideDir reports whether path is the same as dir or a descendant
// of dir, after resolving symlinks on both sides. Returns false on any
// resolution error (conservative: when in doubt, treat as outside).
//
// Resolves the PARENT of path rather than path itself, which handles the
// common "target file does not yet exist" case: on macOS /tmp is a
// symlink to /private/tmp, so asymmetric EvalSymlinks on a nonexistent
// file vs its existing parent would otherwise produce a spurious false.
// Callers (gitAddFile) always pass a path whose parent exists (either
// beadsDir, which FindBeadsDir verified, or a directory just created by
// the export write), so this single-level resolution is sufficient.
func pathInsideDir(path, dir string) bool {
absPath, err := filepath.Abs(path)
if err != nil {
return false
}
absDir, err := filepath.Abs(dir)
if err != nil {
return false
}
if r, err := filepath.EvalSymlinks(filepath.Dir(absPath)); err == nil {
absPath = filepath.Join(r, filepath.Base(absPath))
}
if r, err := filepath.EvalSymlinks(absDir); err == nil {
absDir = r
}
sep := string(filepath.Separator)
return absPath == absDir || strings.HasPrefix(absPath, absDir+sep)
}