project

package
v1.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package project manages on-disk project entries at `<BaseDir>/projects/<id>/` (managed) or any user-supplied absolute path (custom).

A Project is a bundle of: 1 folder (the agent cwd), defaults (preset/provider/system_addon), pinned sessions, icon, and display name. Sessions reference a project via Meta.ProjectID.

Storage layout:

projects/<id>/
  meta.json        — project meta (this package owns it)
  files/           — managed cwd (only when CustomPath is empty)

Index

Constants

View Source
const (
	ButtonOnTicket = "ticket"
	ButtonOnBoard  = "board"
)

Button placements — WHERE a custom button is drawn, and therefore what clicking it is about.

A ticket button acts on the one ticket whose page it sits on; a board button acts on the LIST the toolbar is filtering, and so carries the filter (who, which columns) instead of a single ticket. Two different questions, so they are two different events — see ticket.EventAction and ticket.EventBoardAction.

The empty string means ButtonOnTicket: every button saved before this field existed was a ticket-page button, and an upgrade must not move them onto the board.

View Source
const (
	ChannelKindAny     = ""
	ChannelKindDM      = "dm"
	ChannelKindChannel = "channel"
	ChannelKindThread  = "thread"
)

Channel kinds an AutoCreateRule can be narrowed to. A DM is somebody's private conversation, so "track everything from Slack except DMs" has to be expressible as one rule rather than a list of channels.

View Source
const (
	StatusOpen       = "open"
	StatusInProgress = "in_progress"
	StatusWaiting    = "waiting"
	StatusDone       = "done"
)

Built-in status keys. A project that never edits its statuses uses exactly these, so existing tickets keep working unchanged.

View Source
const AgentTag = "wick:team"

AgentTag marks a project the Team app made to hold an agent's persona (Captain included). Such a project is left out of the sidebar's Projects list; it stays reachable by URL and from the agent. A project an agent was pointed at by the user carries no tag and keeps showing.

Namespaced so a user's own "agent" label never hides their project. Project tags are not validated, so the ':' is safe.

View Source
const DefaultName = "default"

DefaultName is the name of the built-in project that ships with every fresh install.

View Source
const PersonalTag = "personal"

PersonalTag marks the project auto-created for a user as their permanent default. It's the explicit, self-documenting flag used by IsProtected to keep the project undeletable — clearer than inferring "personal" from the owner field or the 👤 icon (which a user could change).

View Source
const VisibleTag = "wick:team-visible"

VisibleTag keeps an agent project (one carrying AgentTag) in the sidebar's Projects list as well. A tag rather than a meta field, so projects written before it decode to "hidden", as they always were.

Variables

This section is empty.

Functions

func CanAccess added in v0.25.0

func CanAccess(meta Meta, acc Access) bool

CanAccess reports whether meta is visible to acc. Mirrors the Service.CanAccessTool rule (admin bypass, untagged = open, otherwise tag match) and adds the project owner rule. Checked in order:

  • admins/owners see every project
  • a project with no owner and no tags is shared (everyone)
  • the owner sees their own project
  • a user carrying any of the project's tags sees it (tag share)

func Delete

func Delete(layout config.Layout, id string) error

Delete removes the project metadata folder. For managed projects: also removes projects/<id>/ (including files/). For custom projects: the external folder is NOT touched.

Two projects are protected from deletion:

  • the built-in "default" project (matched by name)
  • any personal project (one carrying the PersonalTag) — the project auto-created for a user is their permanent default and cannot be removed. Use IsProtected to check this without attempting a delete.

func EnsureDefault

func EnsureDefault(layout config.Layout, newID func() string) error

EnsureDefault creates the "default" project if no projects exist yet. Called from Bootstrap after migration so fresh installs always have a usable project.

func Exists

func Exists(layout config.Layout, id string) bool

Exists reports whether a project with the given id exists on disk.

func FindPersonalProject added in v0.17.0

func FindPersonalProject(layout config.Layout, userID string) (string, error)

FindPersonalProject returns the project ID owned by userID, or "" if none exists. It scans all projects on disk looking for a matching OwnerUserID field.

func IsAgentProject added in v1.2.9

func IsAgentProject(meta Meta) bool

IsAgentProject reports whether meta carries AgentTag.

func IsProtected added in v0.28.2

func IsProtected(meta Meta) bool

IsProtected reports whether meta names a project that cannot be deleted: the built-in "default" project (matched by name), or a personal project (one carrying PersonalTag — the auto-created per-user default). The UI uses this to hide/disable the delete control.

func List

func List(layout config.Layout) ([]string, error)

List returns every project ID found on disk (sorted).

func ListVisibleTo added in v0.25.0

func ListVisibleTo(layout config.Layout, acc Access) ([]string, error)

ListVisibleTo returns the IDs of projects acc may see, sorted like List. Use this for every user-facing project enumeration (channel default dropdown, pickers) instead of List, which returns all projects on disk.

func MigrateWorkspacesToProjects

func MigrateWorkspacesToProjects(layout config.Layout, newID func() string, relink func(wsName, projectID string) error) error

MigrateWorkspacesToProjects is idempotent: it is a no-op when any project already exists on disk. Converts each workspace into a project with the same name, folder, and defaults, then relinks all sessions from workspace name to project_id.

Safety:

  • Skips entirely if projects/ is non-empty.
  • os.Rename is used for managed files/ — atomic on same-FS.
  • Session meta is written only after the project is created.
  • Legacy workspaces/ dir is kept on disk (not deleted) for safety.

func RelinkSessions

func RelinkSessions(layout config.Layout, wsName, projectID string) error

RelinkSessions is the concrete relink callback used at boot: scans all session dirs and updates meta.project_id for sessions that reference the old workspace name. Uses a raw map round-trip to preserve all existing fields.

func ResolvePath

func ResolvePath(layout config.Layout, id string) (string, error)

ResolvePath returns the cwd for agent subprocesses bound to this project. Custom paths win; managed falls back to projects/<id>/files/.

func RewriteProvider added in v0.28.1

func RewriteProvider(layout config.Layout, oldKey, newKey string) (int, error)

RewriteProvider re-points every project whose Defaults.Provider equals oldKey to newKey, persisting each change. Used when a provider instance is renamed so project defaults follow the new "type/name" automatically (live sessions are intentionally left alone — they keep the old key and must be re-pointed by the user). Returns the number of projects updated. A best-effort op: a single project's load/save failure is logged via the returned error only if EVERY candidate failed; partial success still returns the count of those that saved.

func SaveMeta

func SaveMeta(layout config.Layout, id string, meta Meta) error

SaveMeta atomically rewrites projects/<id>/meta.json and bumps UpdatedAt.

func SetShowInProjects added in v1.2.9

func SetShowInProjects(meta *Meta, on bool) bool

SetShowInProjects adds or drops VisibleTag. Returns whether meta changed.

func ShowsInProjects added in v1.2.9

func ShowsInProjects(meta Meta) bool

ShowsInProjects reports whether meta is listed in the sidebar's Projects: every ordinary project, and an agent project only with VisibleTag.

func ValidID added in v1.16.0

func ValidID(id string) bool

ValidID reports whether id can name a project (or a ticket) on disk: one path segment — no separator, no "..", no leading dot, no "%", no control character, at most 128 bytes. Ids come from URLs and tool input, so a read checks it before joining id into a path; an id that fails is simply not found.

Types

type Access added in v0.25.0

type Access struct {
	UserID  string
	TagIDs  []string
	IsAdmin bool
}

Access carries the caller identity used to filter project visibility. Build it in the handler from the request context so this package keeps no login/http imports:

project.Access{
    UserID:  user.ID,
    TagIDs:  login.GetUserTagIDs(ctx),
    IsAdmin: user.IsAdmin(),
}

type AutoCreateRule added in v0.40.0

type AutoCreateRule struct {
	// Origin scopes the rule to where the session came from: "ui",
	// "slack", "telegram", "rest", … or "*" for any.
	Origin string `json:"origin"`
	// ChannelKind narrows a channel-origin rule to dm / channel / thread.
	// Empty means any. Ignored for non-channel origins.
	ChannelKind string `json:"channel_kind,omitempty"`
	// Match is an optional text condition on the session's first message:
	//
	//	""              — origin alone decides
	//	contains:<text> — case-insensitive substring
	//	regex:<expr>    — Go regular expression
	//
	// A regex that does not compile is refused when the config is saved,
	// rather than silently never matching.
	Match string `json:"match,omitempty"`
	// Enabled lets a rule be parked without losing how it was written.
	Enabled bool `json:"enabled"`
	// Title optionally templates the new ticket's title. "{message}" is
	// replaced with the first message (truncated), "{origin}" with the
	// origin. Empty falls back to the message itself.
	Title string `json:"title,omitempty"`
}

AutoCreateRule is one condition under which a session is given a ticket.

type CreateOptions

type CreateOptions struct {
	ID          string // pre-assigned UUID; generated if empty
	Name        string
	Icon        string
	Description string
	CustomPath  string
	Defaults    Defaults
	Tags        []string
	OwnerUserID string
	Widget      config.WidgetPolicy
}

CreateOptions describes a new project.

func PersonalProjectOptions added in v0.17.0

func PersonalProjectOptions(newID, userID, displayName string) CreateOptions

PersonalProjectOptions returns CreateOptions pre-filled for a personal project owned by userID. The caller is responsible for generating a unique ID and calling Create (or the registry manager's CreateProject) with the result.

type Defaults

type Defaults struct {
	Preset   string `json:"preset,omitempty"`
	Provider string `json:"provider,omitempty"`
	// Model pins which model on Provider this project runs, in that
	// instance's own id space — for wick that is "<entryID>@<vendorModelID>",
	// i.e. down to the leaf of a live set.
	//
	// Meaningless without Provider, and never applied across a provider
	// change: a pin belongs to the instance it was chosen on. Empty means
	// "let the instance pick its own default", which is a real choice and
	// not a missing value.
	Model       string `json:"model,omitempty"`
	SystemAddon string `json:"system_addon,omitempty"`
}

Defaults holds the preset/provider/model/system_addon that new sessions in this project inherit when not explicitly overridden.

type Meta

type Meta struct {
	ID             string    `json:"id"`
	Name           string    `json:"name"`
	Icon           string    `json:"icon,omitempty"`
	Description    string    `json:"description,omitempty"`
	CustomPath     string    `json:"custom_path,omitempty"`
	Defaults       Defaults  `json:"defaults"`
	PinnedSessions []string  `json:"pinned_sessions,omitempty"`
	Tags           []string  `json:"tags,omitempty"`
	OwnerUserID    string    `json:"owner_user_id,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`

	// Widget is this project's HTML-artifact CSP override. Zero value
	// (Override false) means "inherit the global policy", which is what
	// every meta.json written before this field decodes to — so no
	// migration is needed. Resolve it with config.Resolve.
	Widget config.WidgetPolicy `json:"widget,omitempty"`

	// Ticket is this project's ticket-mode configuration. Zero value =
	// off (see TicketConfig) — sessions stay plain chat sessions.
	Ticket TicketConfig `json:"ticket,omitempty"`
}

Meta is the persisted shape of a project.

type Project

type Project struct {
	Meta Meta `json:"meta"`
}

Project is the in-memory view: meta only (no session list — that lives in the registry).

func Create

func Create(layout config.Layout, opt CreateOptions) (Project, error)

Create materialises the on-disk project entry. For managed projects (CustomPath=="") it also creates projects/<id>/files/. Custom paths are not created — they must already exist.

func Load

func Load(layout config.Layout, id string) (Project, error)

Load reads projects/<id>/meta.json.

func (Project) ID

func (p Project) ID() string

ID returns the project's UUID.

func (Project) ResolveWidget added in v0.38.2

func (p Project) ResolveWidget(global config.GeneralConfig) config.WidgetPolicy

ResolveWidget returns the effective widget CSP policy for this project: the global policy when the project does not override it, otherwise the project's own modes with its allowlist appended to the global one. See config.Resolve for the exact semantics.

type TicketButton added in v1.2.9

type TicketButton struct {
	// ID is stable across edits, minted on first save. It travels in the
	// event so a receiver serving several buttons can tell them apart.
	ID    string `json:"id"`
	Label string `json:"label"`
	URL   string `json:"url"`
	// Placement is ButtonOnTicket (default) or ButtonOnBoard.
	Placement string `json:"placement,omitempty"`
}

TicketButton is one custom action, rendered either on a ticket's page or in the ticket list's toolbar (see Placement).

Clicking it POSTs an event envelope (the actor, this button's id, and either the full ticket or the list's filter) to URL and reports the response to the clicker. One label, one URL — anything smarter belongs in the receiver.

func (TicketButton) On added in v1.2.9

func (b TicketButton) On(placement string) bool

On reports whether this button belongs at placement, treating an empty Placement as ButtonOnTicket.

type TicketConfig added in v0.40.0

type TicketConfig struct {
	Enabled bool          `json:"enabled,omitempty"`
	Fields  []TicketField `json:"fields,omitempty"`
	// Statuses are this project's board columns, in order. Empty means the
	// built-in set (DefaultTicketStatuses) — which is what every project
	// configured before statuses were editable decodes to.
	Statuses []TicketStatus `json:"statuses,omitempty"`
	// FollowupAfterSec: a non-done ticket untouched for this long is
	// stale — the sweeper wakes the session's agent with FollowupPrompt
	// (a system info turn, not a user message) and the agent decides
	// what to do. Repeats every window while the ticket stays stale.
	FollowupAfterSec int64  `json:"followup_after_sec,omitempty"`
	FollowupPrompt   string `json:"followup_prompt,omitempty"`
	// AutoResolveAfterSec: a non-done ticket untouched for this long is
	// closed — status set to done by the sweeper, no agent spawn.
	AutoResolveAfterSec int64 `json:"auto_resolve_after_sec,omitempty"`

	// AutoCreate decides when a new session gets a ticket of its own with
	// nobody asking for one. Empty = off, which is what every project
	// starts as. Rules are tried in order and the FIRST match wins, so a
	// narrow exception belongs above the broad rule it carves out of.
	AutoCreate []AutoCreateRule `json:"auto_create,omitempty"`

	// Integrations wires the board to the outside world — outbound webhooks,
	// the token-authed REST surface, and the custom ticket buttons. Zero
	// value = all off.
	Integrations TicketIntegrations `json:"integrations,omitempty"`
}

TicketConfig turns a project's sessions into ticket cards. The zero value means the feature is off — every meta.json written before this field existed decodes to off, so no migration is needed.

Durations are plain seconds (not time.Duration) so the JSON contract with the settings UI stays a bare number. 0 = that automation is off.

func (TicketConfig) ActiveWebhooks added in v1.2.9

func (c TicketConfig) ActiveWebhooks(event string) []TicketWebhook

ActiveWebhooks returns the enabled webhooks that want event name.

func (TicketConfig) ButtonByID added in v1.2.9

func (c TicketConfig) ButtonByID(id string) (TicketButton, bool)

ButtonByID finds one of the project's ticket buttons.

func (TicketConfig) ButtonsOn added in v1.2.9

func (c TicketConfig) ButtonsOn(placement string) []TicketButton

ButtonsOn returns the project's buttons for one placement, in config order — what a page renders.

func (TicketConfig) CardFields added in v1.2.9

func (c TicketConfig) CardFields(values map[string]string) map[string]string

CardFields filters a ticket's field values down to what the board card draws: schema fields explicitly marked show_on_card, in no particular order (the client orders by schema). Values written outside the schema — the REST surface accepts any key — stay stored and stay on the ticket's page, but never reach a card: the board is a glance, not a record.

func (TicketConfig) FirstStatus added in v0.40.1

func (c TicketConfig) FirstStatus() string

FirstStatus is where a new ticket lands when none was given.

func (TicketConfig) HasStatus added in v0.40.1

func (c TicketConfig) HasStatus(key string) bool

HasStatus reports whether key is one of this project's statuses.

func (TicketConfig) StatusKeys added in v0.40.1

func (c TicketConfig) StatusKeys() []string

StatusKeys returns just the keys, in board order.

func (TicketConfig) StatusLabel added in v0.40.1

func (c TicketConfig) StatusLabel(key string) string

StatusLabel returns a status's display label, falling back to its key so a board never draws a blank column header.

func (TicketConfig) StatusList added in v0.40.1

func (c TicketConfig) StatusList() []TicketStatus

StatusList returns the project's statuses, falling back to the built-in set. Read through this rather than the field: an empty list means "not customised", not "no columns", and a board with no columns would be a dead end.

func (TicketConfig) TerminalStatus added in v0.40.1

func (c TicketConfig) TerminalStatus() string

TerminalStatus is the stage that means the work is finished — what auto-resolve moves a ticket to, and what the followup timer treats as "leave it alone". Falls back to the last status when nothing is marked, which is the least surprising reading of a board's final column.

type TicketField added in v0.40.0

type TicketField struct {
	Key      string   `json:"key"`   // snake_case identifier, unique within the project
	Label    string   `json:"label"` // shown in the card and the edit form
	Type     string   `json:"type"`  // "text" | "select"
	Options  []string `json:"options,omitempty"`
	Required bool     `json:"required,omitempty"`
	// ShowOnCard puts this field's value on the board card. Off by default:
	// a card is a glance, and every chip on it is one more thing between the
	// eye and the title. The full set is always on the ticket's own page.
	ShowOnCard bool `json:"show_on_card,omitempty"`
}

TicketField is one custom field in a project's ticket schema. Values live per session in session.Meta.Ticket.Fields keyed by Key.

func DefaultTicketFields added in v0.40.0

func DefaultTicketFields() []TicketField

DefaultTicketFields returns the schema seeded when a project enables ticket mode with no fields configured yet.

type TicketIntegrations added in v1.2.9

type TicketIntegrations struct {
	// APIEnabled opens the ticket REST endpoints to Personal Access Token
	// auth for this project. Off by default: the board is reachable from
	// the browser either way, and a project should have to opt in before a
	// bearer token can move its work.
	APIEnabled bool `json:"api_enabled,omitempty"`
	// Webhooks are the endpoints notified when this project's tickets
	// change. Order is display order only.
	Webhooks []TicketWebhook `json:"webhooks,omitempty"`
	// Buttons are custom actions on a ticket's page ("Sync to Notion") or
	// in the ticket list's toolbar ("Pull my tickets from Notion"), by
	// their Placement. Clicking one POSTs to that button's URL — see
	// TicketButton.
	Buttons []TicketButton `json:"buttons,omitempty"`
}

TicketIntegrations wires a project's board to the outside world: outbound webhooks that fire when a ticket changes, and a token-authed REST surface so another system can create and move tickets.

The zero value means both are off, so every meta.json written before this field existed decodes to "no integrations" and nothing starts talking to the network because of an upgrade.

type TicketStatus added in v0.40.1

type TicketStatus struct {
	Key   string `json:"key"`
	Label string `json:"label,omitempty"`
	// Terminal marks the stage that means the work is over. Exactly one
	// status carries it.
	Terminal bool `json:"terminal,omitempty"`
}

TicketStatus is one column on a project's board.

Statuses are per project because what a team calls its stages is theirs to name — "triage → coding → review → shipped" is as valid as the defaults. Two things are structural rather than cosmetic:

  • Key is what a ticket stores and what the MCP surface accepts. It is stable; Label is what the board draws and can be reworded freely.
  • Exactly one status must be Terminal. The stale-followup and auto-resolve timers need to know which stage means "finished", or a sweeper would nag tickets that are already done and auto-resolve would have nowhere to move them.

func DefaultTicketStatuses added in v0.40.1

func DefaultTicketStatuses() []TicketStatus

DefaultTicketStatuses is the set a project starts with.

type TicketWebhook added in v1.2.9

type TicketWebhook struct {
	// ID is stable across edits so a delivery log can be kept per webhook
	// even as its URL or name is reworded.
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	URL  string `json:"url"`
	// Secret keys the HMAC-SHA256 signature sent as X-Wick-Signature. Empty
	// means unsigned — allowed (a receiver on a private network may not
	// need it) but the UI nudges against it.
	//
	// Never rendered back to a client: the API redacts it on read, and a
	// blank value on save means "keep the stored one" rather than "clear
	// it", so editing a webhook's URL cannot silently unsign it.
	Secret string `json:"secret,omitempty"`
	// Events filters which events reach this endpoint. Empty means all of
	// them, which is the least surprising default for a fresh webhook.
	Events []string `json:"events,omitempty"`
	// Headers are extra request headers, for receivers that need a static
	// API key or a routing hint alongside the signature.
	Headers map[string]string `json:"headers,omitempty"`
	// Enabled parks an endpoint without losing how it was configured.
	Enabled bool `json:"enabled"`
}

TicketWebhook is one outbound endpoint.

func (TicketWebhook) WantsEvent added in v1.2.9

func (w TicketWebhook) WantsEvent(name string) bool

WantsEvent reports whether this webhook should receive event name.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL