@happyvertical/smrt-projects

Provider-agnostic project management models for the s-m-r-t framework. Manages repositories, issues, pull requests, and project boards with sync support for external providers (GitHub, GitLab, etc.).

Installation

pnpm add @happyvertical/smrt-projects

Usage

import {
  Repository, RepositoryCollection,
  Issue, IssueCollection,
  PullRequest, PullRequestCollection,
  Project, ProjectCollection
} from '@happyvertical/smrt-projects';

// Track a repository (token resolved from env var at runtime)
const repos = await RepositoryCollection.create({ db });
const repo = await repos.create({
  owner: 'org',
  name: 'my-app',
  providerType: 'github',
  tokenConfigKey: 'GITHUB_TOKEN',
});
await repo.save();

// Sync repository metadata from GitHub
await repo.sync();

// Discover and sync issues
const issues = await repo.getIssues({ state: 'open' });

// Living Spec: AI-synthesize comments into updated issue body
const result = await issue.incorporateFeedback({ apply: true });

// Rollback to original body
await issue.rollback();

API

Models

Export	Description
Repository	Git repository with provider integration. Methods: sync(), getIssues(), getPullRequests(), createIssue(), createPullRequest(), summarizeActivity()
Issue	Issue/ticket (STI base). Methods: sync(), incorporateFeedback(), rollback(), suggestLabels(), close(), addLabels(), addComment()
PullRequest	Pull request (STI subclass of Issue). Methods: sync(), summarize(), merge(), markReady(), convertToDraft(), requestReviewers(), findLinkedIssue()
Project	Project board (GitHub Projects V2). Methods: sync(), addItem(), moveItem(), listItems(), updateItemStatus(), analyzeHealth()
Comment	Comment on an issue or PR. AI methods: isQuestion(), isApproval(), requestsChanges(), extractActionItems(), summarize()
Label	Label/tag for issues. Methods: isTypeLabel(), isPriorityLabel(), getCategory(), createInRepository()

Collections

Export	Key Methods
RepositoryCollection	Standard CRUD
IssueCollection	discover(), findByRepository(), findOpen(), findByLabel(), findByAssignee(), findNeedingReview(), findWithUnincorporatedFeedback(), batchSync()
PullRequestCollection	discover(), findByRepository(), findOpen(), batchSync()
ProjectCollection	Standard CRUD, findByTitle()

STI Hierarchy

PullRequest extends Issue via single-table inheritance. Both share the same table, discriminated by _meta_type. PullRequest adds headRef, baseRef, merged, draft, additions, deletions, changedFiles.

Constants

PROJECTS_MODULE_META, PROJECTS_UI_SLOTS

Key Types

RepositoryProviderType (github | gitlab | bitbucket | azure), ProjectProviderType (github | jira | linear | zenhub), ProjectStatus, SyncStatus, SyncOptions, SearchFilters, CreateIssueInput, CreatePRInput, MergeMethod, IncorporateFeedbackOptions, IncorporateFeedbackResult, ProjectItem, ItemFilters

Options Types

RepositoryOptions, IssueOptions, PullRequestOptions, ProjectOptions, CommentOptions, LabelOptions

Key Patterns

• Token config reference: stores env var name (tokenConfigKey: 'GITHUB_TOKEN'), not the token itself. Resolved at runtime from process.env or getModuleConfig()
• Living Spec (incorporateFeedback()): AI synthesizes issue comments into updated body. Supports preview mode and rollback()
• Sync throttle: sync operations skip if called within 5 minutes (override with { force: true })
• Provider-agnostic: GitHub primary, GitLab/Bitbucket/Azure types defined. Uses @happyvertical/repos and @happyvertical/projects SDK packages

Dependencies

• @happyvertical/smrt-core -- ORM and code generation
• @happyvertical/smrt-config -- configuration loading
• @happyvertical/smrt-tenancy -- multi-tenant scoping
• @happyvertical/smrt-types -- shared type definitions
• @happyvertical/repos -- repository provider SDK
• @happyvertical/projects -- project board provider SDK
• Peer: @happyvertical/smrt-svelte

Contributor guide

See AGENTS.md for package architecture, invariants, validation, and contributor guidance.