project

Documentation

Index

• Constants
• Variables
• type CreatedEvent
• type DeletedEvent
• type InitRequiredEvent
• type Instance
• type Manager
  • func NewManager(ctx context.Context, service Service) (*Manager, error)
  • func (m *Manager) Activate(ctx context.Context, projectID string) error
  • func (m *Manager) ActiveID() string
  • func (m *Manager) ActiveProject(ctx context.Context) (*Project, error)
  • func (m *Manager) CompleteInit(ctx context.Context, projectID string) error
  • func (m *Manager) Deactivate(_ context.Context) error
  • func (m *Manager) List(ctx context.Context) ([]Project, error)
  • func (m *Manager) ListSessions(_ context.Context, projectID string) ([]sessionEntry, error)
  • func (m *Manager) Register(ctx context.Context, name, path string) (*Project, error)
  • func (m *Manager) Rename(ctx context.Context, projectID, newName string) error
  • func (m *Manager) SeedFromGlobal(ctx context.Context)
  • func (m *Manager) Shutdown()
  • func (m *Manager) Subscribe(ctx context.Context) <-chan pubsub.Event[ManagerEvent]
  • func (m *Manager) Unregister(ctx context.Context, projectID string) error
• type ManagerEvent
• type ManagerEventType
• type Project
• type Service
  • func NewService(q *db.Queries) Service
• type StatusChangedEvent
• type SwitchedEvent

Constants

const (
	StatusStopped      = "stopped"
	StatusRunning      = "running"
	StatusError        = "error"
	StatusInitializing = "initializing"
	StatusMissing      = "missing" // path no longer exists on disk
)

Status constants for project lifecycle states.

Variables

var ErrProjectNeedsInit = errors.New("project needs initialization: no .pando.toml found at path")

ErrProjectNeedsInit is returned when Activate is called on a project path that has no .pando.toml (or .pando.json) configuration file. The caller should guide the user through the init flow before retrying.

Types

type CreatedEvent

type CreatedEvent struct {
	Project Project
}

CreatedEvent is published when a new project is registered.

type DeletedEvent

type DeletedEvent struct {
	ProjectID string
}

DeletedEvent is published when a project is removed from the registry.

type InitRequiredEvent

type InitRequiredEvent struct {
	ProjectID string
	Path      string
}

InitRequiredEvent is published when activation is attempted on an uninitialized path.

type Instance

type Instance struct {
	Project Project
	// contains filtered or unexported fields
}

Instance represents a running (or stopped) child Pando ACP process for a registered project directory.

type Manager

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

Manager tracks child Pando ACP processes for registered project directories and routes lifecycle events to subscribers via a generic pubsub broker.

func NewManager

func NewManager(ctx context.Context, service Service) (*Manager, error)

NewManager creates a new Manager. Call Shutdown() when done to stop all child processes and release resources.

func (*Manager) Activate

func (m *Manager) Activate(ctx context.Context, projectID string) error

Activate starts (if needed) the child ACP process for projectID and makes it the active project. Returns ErrProjectNeedsInit if the path has no .pando.toml or .pando.json configuration file.

func (*Manager) ActiveID

func (m *Manager) ActiveID() string

ActiveID returns the currently active project ID. An empty string means the main (non-project) pando instance is active.

func (*Manager) ActiveProject

func (m *Manager) ActiveProject(ctx context.Context) (*Project, error)

ActiveProject returns the currently active Project, or nil when the main instance is active.

func (*Manager) CompleteInit

func (m *Manager) CompleteInit(ctx context.Context, projectID string) error

CompleteInit initializes the Pando configuration at the project's directory and then activates the project. It is called after the user confirms the initialization prompt shown when Activate returns ErrProjectNeedsInit.

It creates .pando.toml, .pando/ directory structure, and the init flag, then retries Activate. On success the project becomes the active project.

func (*Manager) Deactivate

func (m *Manager) Deactivate(_ context.Context) error

Deactivate clears the active project (the main pando instance becomes active again).

func (*Manager) List

func (m *Manager) List(ctx context.Context) ([]Project, error)

List returns all registered projects from the underlying service.

func (*Manager) ListSessions

func (m *Manager) ListSessions(_ context.Context, projectID string) ([]sessionEntry, error)

ListSessions returns the cached session list for the given project instance. Returns nil when the project is not currently running.

NOTE: Actual session fetching will be implemented in Phase 5 via the REST API. For now this returns the in-memory cache which starts empty and is refreshed by future implementations.

func (*Manager) Register

func (m *Manager) Register(ctx context.Context, name, path string) (*Project, error)

Register adds a new project path to the registry. If name is empty, filepath.Base(path) is used. The path is expanded (~ resolved) and symlinks are evaluated before storing.

func (*Manager) Rename

func (m *Manager) Rename(ctx context.Context, projectID, newName string) error

Rename changes the display name of a registered project and propagates the change to the global projects registry so other instances can see it.

func (*Manager) SeedFromGlobal

func (m *Manager) SeedFromGlobal(ctx context.Context)

SeedFromGlobal upserts every entry from the global projects registry into the local DB so that any Pando instance can see all known projects. Entries whose path is already registered are skipped. This is called once during startup.

func (*Manager) Shutdown

func (m *Manager) Shutdown()

Shutdown stops all running child processes and cleans up resources. It is safe to call Shutdown more than once.

func (*Manager) Subscribe

func (m *Manager) Subscribe(ctx context.Context) <-chan pubsub.Event[ManagerEvent]

Subscribe returns a channel of ManagerEvents for real-time notifications.

func (*Manager) Unregister

func (m *Manager) Unregister(ctx context.Context, projectID string) error

Unregister removes a project from the registry and stops its running instance (if any).

type ManagerEvent

type ManagerEvent struct {
	Type      ManagerEventType
	ProjectID string
	Status    string
	Error     string
}

ManagerEvent is the union event type published by Manager.

type ManagerEventType

type ManagerEventType string

ManagerEventType identifies the kind of ManagerEvent.

const (
	// EvProjectSwitched is published when the active project changes.
	EvProjectSwitched ManagerEventType = "switched"
	// EvStatusChanged is published when a project's running status changes.
	EvStatusChanged ManagerEventType = "status_changed"
	// EvInitRequired is published when activation fails because the project
	// path has no Pando configuration file.
	EvInitRequired ManagerEventType = "init_required"
)

type Project

type Project struct {
	ID          string
	Name        string
	Path        string
	Status      string
	Initialized bool
	ACPPID      int
	ACPPort     int
	LastOpened  *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Project represents a registered project directory managed by Pando.

type Service

type Service interface {
	// Create registers a new project directory.
	// name defaults to filepath.Base(path) if empty.
	Create(ctx context.Context, name, path string) (*Project, error)

	// Get retrieves a project by ID.
	Get(ctx context.Context, id string) (*Project, error)

	// GetByPath retrieves a project by its directory path.
	GetByPath(ctx context.Context, path string) (*Project, error)

	// List returns all registered projects, newest first.
	List(ctx context.Context) ([]Project, error)

	// UpdateStatus updates the running state and optional process info.
	// pid and port should be 0 when not applicable.
	UpdateStatus(ctx context.Context, id, status string, pid, port int) error

	// MarkInitialized marks the project's config as having been initialized.
	MarkInitialized(ctx context.Context, id string) error

	// TouchLastOpened records the current time as last_opened for the project.
	TouchLastOpened(ctx context.Context, id string) error

	// Rename updates the display name of a project.
	Rename(ctx context.Context, id, name string) error

	// Delete removes a project from the registry (does NOT delete files).
	Delete(ctx context.Context, id string) error
}

Service defines operations for managing registered projects.

func NewService

func NewService(q *db.Queries) Service

NewService creates a new project service backed by the given DB queries.

type StatusChangedEvent

type StatusChangedEvent struct {
	ProjectID string
	OldStatus string
	NewStatus string
}

StatusChangedEvent is published when a project's status changes.

type SwitchedEvent

type SwitchedEvent struct {
	ProjectID string // empty string means "back to main instance"
}

SwitchedEvent is published when the active project changes.