imports

type Entry struct {
	Handle    string    `json:"handle"`
	Path      string    `json:"path"`
	Sidecar   Sidecar   `json:"sidecar"`
	ExpiresIn string    `json:"expires_in,omitempty"`
	Pinned    bool      `json:"pinned"`
	Expired   bool      `json:"expired"`
	Now       time.Time `json:"-"`
}

type Manager struct {
	// contains filtered or unexported fields
}

type Options struct {
	// ImportsDir overrides the default relative directory. Honoured
	// before the PULSE_IMPORTS_DIR env var.
	ImportsDir string

	// DefaultTTL overrides the default TTL. Honoured before the
	// PULSE_IMPORT_TTL env var. Zero falls back to env, then to
	// the package DefaultTTL.
	DefaultTTL time.Duration

	// SourceFS is the filesystem used when SourcePath is absolute. When
	// nil, the Manager defaults to afero.NewOsFs() jailed to
	// SourceJailRoot. Set explicitly when callers want to manage
	// access themselves (e.g., a pre-chrooted MemMapFs); doing so
	// disables the jail check — the explicit fs IS the boundary.
	SourceFS afero.Fs

	// SourceJailRoot constrains the default SourceFS to a directory.
	// Empty string defaults to os.Getwd() at construction so an MCP
	// server invocation reaches only files under the directory it was
	// launched from. Ignored when SourceFS is set explicitly.
	SourceJailRoot string

	// Now is the clock; injected for testing. Defaults to time.Now.
	Now func() time.Time
}

type Result struct {
	Handle       string           `json:"handle"`
	Path         string           `json:"path"`
	Format       string           `json:"format"`
	Managed      bool             `json:"managed"`
	RowsImported int              `json:"rows_imported,omitempty"`
	ImportedAt   time.Time        `json:"imported_at,omitzero"`
	ExpiresAt    *time.Time       `json:"expires_at,omitempty"`
	TTLSeconds   int64            `json:"ttl_seconds,omitempty"`
	Schema       *encoding.Schema `json:"-"`
}

type Sidecar struct {
	Handle       string    `json:"handle"`
	Format       string    `json:"format"`
	SourcePath   string    `json:"source_path"`
	SourceFormat string    `json:"source_format"`
	ImportedAt   time.Time `json:"imported_at"`
	ExpiresAt    time.Time `json:"expires_at,omitzero"`
	TTLSeconds   int64     `json:"ttl_seconds"`
	RowsImported int       `json:"rows_imported"`
}

type Spec struct {
	// SourcePath is the filesystem path of the source file, relative to
	// the Pulse fs root. Required when InlineBytes is unset.
	SourcePath string

	// Format overrides extension-based detection. Use the identifiers
	// from io/format (csv, tsv, ndjson, jsonarray, parquet, arrow,
	// excel, pulse). When empty, FromExt(SourcePath) is used.
	Format string

	// Handle is the desired managed name (without extension). Defaults
	// to the source basename with the original extension stripped.
	// Collisions error unless Overwrite is true.
	Handle string

	// TTL governs how long the import survives in the managed pool.
	// Zero falls back to DefaultTTL. Negative values pin the import
	// (never sweep, never expire).
	TTL time.Duration

	// Sheet is honoured only for Excel sources; ignored otherwise.
	Sheet string

	// Overwrite replaces an existing managed handle of the same name.
	// Defaults to false (collision → PULSE_IMPORT_HANDLE_EXISTS).
	Overwrite bool

	// InlineBytes carries the raw source bytes for in-memory imports.
	// Format must be set explicitly when this is non-nil.
	InlineBytes []byte
}