⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
// The canonical intermediate shape a source adapter (SourceReader, see reader.ts)
// produces. Plain types only, no runtime logic. import-worker.ts converts these
// into itsaplan's own tables; nothing here depends on @repo/db so a future
// Linear or Jira adapter can produce the same shape without pulling in the
// worker's persistence layer.
// itsaplan's own project_column.state_type values (packages/db/src/schema/app.ts).
export type CanonicalStateCategory = 'backlog' | 'unstarted' | 'started' | 'completed' | 'canceled';
export interface CanonicalState {
sourceId: string;
name: string;
category: CanonicalStateCategory;
}
export interface CanonicalLabel {
sourceId: string;
name: string;
color?: string;
}
export interface CanonicalCycle {
sourceId: string;
name: string;
// Date-only ('YYYY-MM-DD'): itsaplan's cycle.startDate/endDate carry no time of day.
startDate: string;
endDate: string;
goal?: string;
}
// itsaplan's own custom_field.field_type values that an import creates.
export type CanonicalCustomFieldType = 'text' | 'number' | 'boolean' | 'datetime' | 'select';
export interface CanonicalCustomField {
sourceId: string;
name: string;
fieldType: CanonicalCustomFieldType;
// The option values of a 'select' field, in the source's order.
options: string[];
}
// A 'select' value is the option's text; a 'datetime' value is an ISO timestamp.
export interface CanonicalCustomFieldValue {
fieldSourceId: string;
value: string | number | boolean | null;
}
export interface CanonicalChecklist {
sourceId: string;
title: string;
items: { content: string; done: boolean }[];
}
// No URL field: an attachment's download URL is a presigned link that expires
// (see docs/dev/plane-import-source-notes.md), so it must never be resolved
// ahead of the phase that actually downloads the bytes. sourceId is what a later
// phase resolves it from again, on demand. sizeBytes is the source's own claim,
// used only to skip an obviously-too-large file before downloading it — the
// size actually stored always comes from the downloaded bytes, never this.
export interface CanonicalAttachment {
sourceId: string;
filename: string;
contentType: string;
sizeBytes: number;
}
export interface CanonicalComment {
sourceId: string;
authorEmail: string | null;
authorName: string;
bodyMarkdown: string;
createdAt: string;
replyToSourceId: string | null;
}
export interface CanonicalRelation {
kind: 'blocks' | 'relates' | 'duplicates';
sourceIssueSourceId: string;
targetIssueSourceId: string;
}
// Comments and attachments are fetched and written per-issue during the Create
// phase, not nested here: keeping this flat means one issue's payload does not
// grow with however many comments or attachments it happens to carry.
export interface CanonicalIssue {
sourceId: string;
// The source's own human-readable issue number (Plane's sequence_id), used only
// to resolve a cross-reference like "ROOMS-524" in another issue's text back to
// this one during the Rewrite phase.
sequenceId: number;
title: string;
descriptionMarkdown: string;
stateSourceId: string;
assigneeEmail: string | null;
watcherEmails: string[];
labelSourceIds: string[];
cycleSourceId: string | null;
parentSourceId: string | null;
priority: string | null;
startDate: string | null;
dueDate: string | null;
customFields: CanonicalCustomFieldValue[];
createdAt: string;
updatedAt: string;
// Set when the source has the issue archived; the issue is created archived.
archivedAt: string | null;
}