@compilr-dev/sdk 0.1.6 → 0.1.8

package/dist/platform/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Platform Types — Canonical data model types for the compilr-dev ecosystem.
+ *
+ * These types define the storage-agnostic data models used across all platform
+ * clients (CLI, web UI, API). They are extracted from the CLI's SQLite-backed
+ * repositories and made async-compatible for future PostgreSQL support.
+ *
+ * Conventions:
+ * - Enums: string literal union types
+ * - Data models: camelCase properties (output types)
+ * - Input types: snake_case properties (matching CLI tool input schemas)
+ */
+export type ProjectType = 'general' | 'web' | 'cli' | 'library' | 'api';
+export type ProjectStatus = 'active' | 'paused' | 'completed' | 'archived';
+export type RepoPattern = 'single' | 'two-repo';
+export type WorkflowMode = 'flexible' | 'guided';
+export type LifecycleState = 'setup' | 'active' | 'maintenance' | 'complete';
+export type WorkItemType = 'feature' | 'bug' | 'tech-debt' | 'chore';
+export type WorkItemStatus = 'backlog' | 'in_progress' | 'completed' | 'skipped';
+export type WorkItemPriority = 'critical' | 'high' | 'medium' | 'low';
+export type GuidedStep = 'plan' | 'implement' | 'test' | 'commit' | 'review';
+export type DocumentType = 'prd' | 'architecture' | 'design' | 'notes' | 'plan';
+export type PlanStatus = 'draft' | 'approved' | 'in_progress' | 'completed' | 'abandoned';
+export interface Project {
+    id: number;
+    name: string;
+    displayName: string;
+    description: string | null;
+    type: ProjectType;
+    status: ProjectStatus;
+    path: string;
+    docsPath: string | null;
+    repoPattern: RepoPattern;
+    language: string | null;
+    framework: string | null;
+    packageManager: string | null;
+    runtimeVersion: string | null;
+    commands: Record<string, string> | null;
+    gitRemote: string | null;
+    gitBranch: string;
+    workflowMode: WorkflowMode;
+    lifecycleState: LifecycleState;
+    currentItemId: string | null;
+    lastContext: Record<string, unknown> | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+    lastActivityAt: Date | null;
+}
+export interface WorkItem {
+    id: number;
+    projectId: number;
+    itemNumber: number;
+    itemId: string;
+    type: WorkItemType;
+    status: WorkItemStatus;
+    priority: WorkItemPriority;
+    guidedStep: GuidedStep | null;
+    owner: string | null;
+    title: string;
+    description: string | null;
+    estimatedEffort: string | null;
+    actualMinutes: number | null;
+    completedAt: Date | null;
+    completedBy: string | null;
+    commitHash: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ProjectDocument {
+    id: number;
+    projectId: number;
+    docType: DocumentType;
+    title: string;
+    content: string;
+    createdAt: Date;
+    updatedAt: Date;
+    status: string | null;
+    workItemId: number | null;
+}
+export interface Plan {
+    id: number;
+    projectId: number;
+    name: string;
+    content: string;
+    status: PlanStatus;
+    workItemId: number | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface PlanSummary {
+    id: number;
+    name: string;
+    status: PlanStatus;
+    workItemId: number | null;
+    workItemTitle?: string;
+    workItemItemId?: string;
+    updatedAt: Date;
+}
+export interface PlanWithWorkItem extends Plan {
+    workItem?: {
+        id: number;
+        itemId: string;
+        title: string;
+        status: string;
+    };
+}
+export interface HistoryEntry {
+    action: string;
+    oldValue: string | null;
+    newValue: string | null;
+    notes: string | null;
+    changedBy: string | null;
+    changedAt: Date;
+}
+export interface CreateProjectInput {
+    name: string;
+    display_name: string;
+    description?: string;
+    type?: ProjectType;
+    path: string;
+    docs_path?: string;
+    repo_pattern?: RepoPattern;
+    language?: string;
+    framework?: string;
+    package_manager?: string;
+    runtime_version?: string;
+    commands?: Record<string, string>;
+    git_remote?: string;
+    git_branch?: string;
+    workflow_mode?: WorkflowMode;
+    metadata?: Record<string, unknown>;
+}
+export interface UpdateProjectInput {
+    display_name?: string;
+    description?: string;
+    type?: ProjectType;
+    status?: ProjectStatus;
+    docs_path?: string;
+    repo_pattern?: RepoPattern;
+    language?: string;
+    framework?: string;
+    package_manager?: string;
+    runtime_version?: string;
+    commands?: Record<string, string>;
+    git_remote?: string;
+    git_branch?: string;
+    workflow_mode?: WorkflowMode;
+    lifecycle_state?: LifecycleState;
+    current_item_id?: string | null;
+    last_context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface ProjectListOptions {
+    status?: ProjectStatus | 'all';
+    type?: ProjectType | 'all';
+    limit?: number;
+    offset?: number;
+}
+export interface CreateWorkItemInput {
+    project_id: number;
+    type: WorkItemType;
+    title: string;
+    description?: string;
+    priority?: WorkItemPriority;
+    estimated_effort?: 'low' | 'medium' | 'high';
+    owner?: string;
+}
+export interface UpdateWorkItemInput {
+    type?: WorkItemType;
+    status?: WorkItemStatus;
+    priority?: WorkItemPriority;
+    guided_step?: GuidedStep | null;
+    owner?: string | null;
+    title?: string;
+    description?: string;
+    estimated_effort?: 'low' | 'medium' | 'high';
+    actual_minutes?: number;
+    commit_hash?: string;
+}
+export interface QueryWorkItemsInput {
+    project_id?: number;
+    status?: WorkItemStatus | 'all';
+    type?: WorkItemType | 'all';
+    priority?: WorkItemPriority | 'all';
+    owner?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CreateDocumentInput {
+    project_id: number;
+    doc_type: DocumentType;
+    title: string;
+    content: string;
+}
+export interface UpdateDocumentInput {
+    title?: string;
+    content?: string;
+}
+export interface CreatePlanInput {
+    project_id: number;
+    name: string;
+    content: string;
+    work_item_id?: number;
+}
+export interface UpdatePlanInput {
+    content?: string;
+    status?: PlanStatus;
+    work_item_id?: number | null;
+}
+export interface ListPlansOptions {
+    status?: PlanStatus | PlanStatus[];
+    work_item_id?: number;
+    limit?: number;
+    order_by?: 'updated_desc' | 'updated_asc' | 'created_desc' | 'name_asc';
+}
+export interface WorkItemQueryResult {
+    items: WorkItem[];
+    total: number;
+    hasMore: boolean;
+}
+export interface ProjectListResult {
+    projects: Project[];
+    total: number;
+}
+export interface BulkCreateItem {
+    type: WorkItemType;
+    title: string;
+    description?: string;
+    priority?: WorkItemPriority;
+    owner?: string;
+}

package/dist/platform/types.js

@@ -0,0 +1,13 @@
+/**
+ * Platform Types — Canonical data model types for the compilr-dev ecosystem.
+ *
+ * These types define the storage-agnostic data models used across all platform
+ * clients (CLI, web UI, API). They are extracted from the CLI's SQLite-backed
+ * repositories and made async-compatible for future PostgreSQL support.
+ *
+ * Conventions:
+ * - Enums: string literal union types
+ * - Data models: camelCase properties (output types)
+ * - Input types: snake_case properties (matching CLI tool input schemas)
+ */
+export {};

package/dist/platform/workflow.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Workflow Step Criteria — Pure logic for guided workflow steps.
+ *
+ * Defines exit criteria, step ordering, and transition rules for the
+ * guided workflow (plan → implement → test → commit → review → complete).
+ *
+ * No DB or CLI dependencies — only imports GuidedStep from types.
+ */
+import type { GuidedStep } from './types.js';
+export interface StepCriteria {
+    /** The guided step */
+    step: GuidedStep;
+    /** Human-readable exit criteria for system prompt */
+    exitCriteria: string[];
+    /** What agent looks for to determine success */
+    successIndicators: string[];
+    /** Maximum attempts for retryable steps (like test) */
+    maxAttempts?: number;
+    /** Can agent advance automatically when criteria met? */
+    autoAdvance: boolean;
+    /** Hint for next action after advancing */
+    nextActionHint: string;
+}
+/** Step order — defines valid step progression */
+export declare const STEP_ORDER: readonly GuidedStep[];
+/** Guided step criteria definitions */
+export declare const GUIDED_STEP_CRITERIA: readonly StepCriteria[];
+/** Get the next step in the workflow */
+export declare function getNextStep(current: GuidedStep | null): GuidedStep | 'complete';
+/** Get step number (1-indexed for display) */
+export declare function getStepNumber(step: GuidedStep): number;
+/** Check if step transition is valid (can only advance to next step) */
+export declare function isValidTransition(from: GuidedStep | null, to: GuidedStep | 'complete'): boolean;
+/** Get criteria for a specific step */
+export declare function getStepCriteria(step: GuidedStep): StepCriteria;
+/** Format step for display (e.g., "IMPLEMENT (2 of 5)") */
+export declare function formatStepDisplay(step: GuidedStep): string;

package/dist/platform/workflow.js

@@ -0,0 +1,108 @@
+/**
+ * Workflow Step Criteria — Pure logic for guided workflow steps.
+ *
+ * Defines exit criteria, step ordering, and transition rules for the
+ * guided workflow (plan → implement → test → commit → review → complete).
+ *
+ * No DB or CLI dependencies — only imports GuidedStep from types.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/** Step order — defines valid step progression */
+export const STEP_ORDER = [
+    'plan',
+    'implement',
+    'test',
+    'commit',
+    'review',
+];
+/** Guided step criteria definitions */
+export const GUIDED_STEP_CRITERIA = [
+    {
+        step: 'plan',
+        exitCriteria: [
+            'Requirements understood and documented',
+            'Approach designed (files to create/modify identified)',
+            'Edge cases considered',
+        ],
+        successIndicators: [
+            'Agent has written a plan in conversation or document',
+            'Agent has identified target files',
+            'No blocking questions remain',
+        ],
+        autoAdvance: true,
+        nextActionHint: 'Start implementing the planned changes',
+    },
+    {
+        step: 'implement',
+        exitCriteria: [
+            'All planned code changes completed',
+            'No placeholder TODOs left',
+            'Code compiles/lints cleanly',
+        ],
+        successIndicators: [
+            'writeFile/edit tools have been called',
+            'Lint command passes (if available)',
+            'No obvious errors in code',
+        ],
+        autoAdvance: true,
+        nextActionHint: 'Run tests to verify the implementation',
+    },
+    {
+        step: 'test',
+        exitCriteria: ['All tests pass', 'OR: User overrides after 2 failed attempts'],
+        successIndicators: ['Test command exits with 0', 'All test assertions pass'],
+        maxAttempts: 2,
+        autoAdvance: true,
+        nextActionHint: 'Commit the changes with a proper message',
+    },
+    {
+        step: 'commit',
+        exitCriteria: ['Changes committed with proper message', 'Commit hash captured'],
+        successIndicators: ['git commit command succeeded', 'Commit hash in output'],
+        autoAdvance: true,
+        nextActionHint: 'Review and confirm ready for next item',
+    },
+    {
+        step: 'review',
+        exitCriteria: ['User confirms ready for next item', 'OR: User wants to do something else'],
+        successIndicators: ['User says "yes", "next", "continue"', 'User explicitly approves'],
+        autoAdvance: false,
+        nextActionHint: 'Pick the next work item from backlog',
+    },
+];
+// =============================================================================
+// Functions
+// =============================================================================
+/** Get the next step in the workflow */
+export function getNextStep(current) {
+    if (current === null)
+        return 'plan';
+    const idx = STEP_ORDER.indexOf(current);
+    if (idx === -1 || idx >= STEP_ORDER.length - 1)
+        return 'complete';
+    return STEP_ORDER[idx + 1];
+}
+/** Get step number (1-indexed for display) */
+export function getStepNumber(step) {
+    return STEP_ORDER.indexOf(step) + 1;
+}
+/** Check if step transition is valid (can only advance to next step) */
+export function isValidTransition(from, to) {
+    const nextStep = getNextStep(from);
+    return nextStep === to;
+}
+/** Get criteria for a specific step */
+export function getStepCriteria(step) {
+    const criteria = GUIDED_STEP_CRITERIA.find((c) => c.step === step);
+    if (!criteria) {
+        throw new Error(`No criteria found for step: ${step}`);
+    }
+    return criteria;
+}
+/** Format step for display (e.g., "IMPLEMENT (2 of 5)") */
+export function formatStepDisplay(step) {
+    const num = getStepNumber(step);
+    return `${step.toUpperCase()} (${String(num)} of ${String(STEP_ORDER.length)})`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",