@kjerneverk/riotplan-format

SQLite-based storage format for RiotPlan with dual format support.

This package provides a storage abstraction layer that supports both directory-based and SQLite .plan formats for RiotPlan plans.

Installation

npm install @kjerneverk/riotplan-format

Features

• Dual Format Support: Store plans as directories (traditional) or SQLite files (portable)
• Storage Abstraction: Unified StorageProvider interface for both formats
• Format Detection: Automatic detection of plan format from path
• Migration Utilities: Convert plans between formats with validation
• Markdown Rendering: Export plans to markdown format
• Type-Safe: Full TypeScript support with comprehensive types

Usage

Creating a SQLite Plan

import { SqliteStorageProvider } from '@kjerneverk/riotplan-format';

const provider = new SqliteStorageProvider('./my-plan.plan');

await provider.initialize({
    id: 'my-plan',
    name: 'My Plan',
    description: 'A sample plan',
    stage: 'idea',
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
    schemaVersion: 1,
});

// Add a step
await provider.addStep({
    number: 1,
    code: 'step-1',
    title: 'First Step',
    status: 'pending',
    content: '# First Step\n\nDescription here.',
});

// Close when done
await provider.close();

Using the Storage Factory

import { createStorageFactory, createProvider } from '@kjerneverk/riotplan-format';

// Create a factory with custom config
const factory = createStorageFactory({
    defaultFormat: 'sqlite',
    sqlite: {
        extension: '.plan',
        walMode: true,
    },
});

// Create a provider based on path
const provider = factory.createProvider('./my-plan.plan');

// Or use the convenience function
const provider2 = createProvider('./another.plan', { format: 'sqlite' });

Format Detection

import { detectPlanFormat, inferFormatFromPath } from '@kjerneverk/riotplan-format';

// Detect format of existing plan
const format = detectPlanFormat('./my-plan'); // 'directory' | 'sqlite' | 'unknown'

// Infer format from path
const inferred = inferFormatFromPath('./my-plan.plan'); // 'sqlite'

Migration Between Formats

import { PlanMigrator, MigrationValidator } from '@kjerneverk/riotplan-format';

const migrator = new PlanMigrator();

// Migrate from source to target
const result = await migrator.migrate(
    sourcePath,
    targetPath,
    sourceProvider,
    targetProvider,
    {
        keepSource: true,
        validate: true,
        onProgress: (progress) => {
            console.log(`${progress.phase}: ${progress.percentage}%`);
        },
    }
);

if (result.success) {
    console.log(`Migrated ${result.stats.stepsConverted} steps`);
}

// Validate migration
const validator = new MigrationValidator();
const validation = await validator.validate(sourceProvider, targetProvider);

Rendering to Markdown

import { renderPlanToMarkdown } from '@kjerneverk/riotplan-format';

const rendered = await renderPlanToMarkdown(provider, {
    includeEvidence: true,
    includeFeedback: true,
    includeSourceInfo: true,
});

// rendered.files: Map<string, string> - SUMMARY.md, STATUS.md, etc.
// rendered.steps: Map<string, string> - 01-step.md, 02-step.md, etc.
// rendered.evidence: Map<string, string> - evidence files
// rendered.feedback: Map<string, string> - feedback files

API Reference

Types

• PlanMetadata - Plan metadata (id, name, stage, timestamps)
• PlanStep - Step definition (number, title, status, content)
• PlanFile - File content (type, filename, content)
• TimelineEvent - Timeline event (type, timestamp, data)
• EvidenceRecord - Evidence record (description, source, content)
• FeedbackRecord - Feedback record (title, content, participants)
• Checkpoint - Checkpoint for state snapshots
• StorageFormat - 'directory' | 'sqlite'

Storage Providers

• StorageProvider - Interface for storage operations
• SqliteStorageProvider - SQLite implementation
• DirectoryStorageProvider - Directory implementation (skeleton)

Configuration

• FormatConfig - Format selection configuration
• SqliteConfig - SQLite-specific options
• DirectoryConfig - Directory-specific options
• mergeFormatConfig() - Merge user config with defaults

Utilities

• detectPlanFormat() - Detect format of existing plan
• inferFormatFromPath() - Infer format from path
• validatePlanPath() - Validate path for format
• ensureFormatExtension() - Add correct extension

Migration

• PlanMigrator - Migrate plans between formats
• MigrationValidator - Validate migration fidelity
• generateTargetPath() - Generate target path for migration
• inferTargetFormat() - Infer opposite format

Rendering

• renderPlanToMarkdown() - Render plan to markdown files

Directory Format Structure

my-plan/
├── SUMMARY.md          # Plan overview
├── STATUS.md           # Current status and progress
├── IDEA.md             # Original idea (optional)
├── SHAPING.md          # Shaping notes (optional)
├── EXECUTION_PLAN.md   # Execution strategy (optional)
├── plan/
│   ├── 01-step-one.md
│   ├── 02-step-two.md
│   └── ...
├── evidence/
│   └── *.md
├── feedback/
│   └── *.md
├── reflections/
│   └── *.md
└── .history/
    ├── timeline.json
    └── checkpoints/
        └── *.json

SQLite Schema

The SQLite format uses a normalized schema with tables for:

• plans - Plan metadata
• plan_steps - Step definitions
• plan_files - File contents
• timeline_events - Timeline events
• evidence_records - Evidence records
• feedback_records - Feedback records
• checkpoints - State snapshots
• step_reflections - Step reflections

Schema version tracking enables future migrations.

License

MIT