@lusipad/pmspec 1.0.0

package/dist/core/changelog-service.d.ts

@@ -0,0 +1,88 @@
+import { ChangelogEntry, ChangelogFile, ChangelogQueryOptions, ChangelogEntityType } from './changelog.js';
+/**
+ * Service for managing changelog operations
+ */
+export declare class ChangelogService {
+    private filePath;
+    constructor(basePath?: string);
+    /**
+     * Initialize the changelog file if it doesn't exist
+     */
+    initialize(): Promise<void>;
+    /**
+     * Read the changelog file
+     */
+    read(): Promise<ChangelogFile>;
+    /**
+     * Write the changelog file
+     */
+    write(data: ChangelogFile): Promise<void>;
+    /**
+     * Add entries to the changelog
+     */
+    addEntries(entries: ChangelogEntry[]): Promise<void>;
+    /**
+     * Record a create action
+     */
+    recordCreate(entityType: ChangelogEntityType, entityId: string, user?: string): Promise<ChangelogEntry>;
+    /**
+     * Record a delete action
+     */
+    recordDelete(entityType: ChangelogEntityType, entityId: string, user?: string): Promise<ChangelogEntry>;
+    /**
+     * Record an update action for a single field
+     */
+    recordUpdate(entityType: ChangelogEntityType, entityId: string, field: string, oldValue: unknown, newValue: unknown, user?: string): Promise<ChangelogEntry | null>;
+    /**
+     * Record multiple field updates at once
+     */
+    recordUpdates(entityType: ChangelogEntityType, entityId: string, changes: Record<string, {
+        oldValue: unknown;
+        newValue: unknown;
+    }>, user?: string): Promise<ChangelogEntry[]>;
+    /**
+     * Query changelog entries
+     */
+    query(options?: ChangelogQueryOptions): Promise<ChangelogEntry[]>;
+    /**
+     * Get history for a specific entity
+     */
+    getEntityHistory(entityId: string): Promise<ChangelogEntry[]>;
+    /**
+     * Get all entries (with optional pagination)
+     */
+    getAll(limit?: number, offset?: number): Promise<{
+        entries: ChangelogEntry[];
+        total: number;
+    }>;
+    /**
+     * Get entries since a specific date
+     */
+    getSince(since: string): Promise<ChangelogEntry[]>;
+    /**
+     * Get changelog summary statistics
+     */
+    getStats(): Promise<{
+        totalEntries: number;
+        byEntityType: Record<string, number>;
+        byAction: Record<string, number>;
+        recentActivity: {
+            last24h: number;
+            last7d: number;
+            last30d: number;
+        };
+    }>;
+    /**
+     * Clear all changelog entries (use with caution)
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Get the default changelog service instance
+ */
+export declare function getChangelogService(): ChangelogService;
+/**
+ * Reset the default service (mainly for testing)
+ */
+export declare function resetChangelogService(): void;
+//# sourceMappingURL=changelog-service.d.ts.map

package/dist/core/changelog-service.js

@@ -0,0 +1,208 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { ChangelogFileSchema, createChangelogEntry, createUpdateEntries, filterChangelogEntries, } from './changelog.js';
+const CHANGELOG_FILE = 'pmspace/changelog.json';
+/**
+ * Service for managing changelog operations
+ */
+export class ChangelogService {
+    filePath;
+    constructor(basePath = process.cwd()) {
+        this.filePath = join(basePath, CHANGELOG_FILE);
+    }
+    /**
+     * Initialize the changelog file if it doesn't exist
+     */
+    async initialize() {
+        try {
+            await readFile(this.filePath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Create directory and file
+                await mkdir(dirname(this.filePath), { recursive: true });
+                const initialData = {
+                    version: '1.0',
+                    lastUpdated: new Date().toISOString(),
+                    entries: [],
+                };
+                await writeFile(this.filePath, JSON.stringify(initialData, null, 2));
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Read the changelog file
+     */
+    async read() {
+        try {
+            const content = await readFile(this.filePath, 'utf-8');
+            const data = JSON.parse(content);
+            return ChangelogFileSchema.parse(data);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Return empty changelog if file doesn't exist
+                return {
+                    version: '1.0',
+                    lastUpdated: new Date().toISOString(),
+                    entries: [],
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write the changelog file
+     */
+    async write(data) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        data.lastUpdated = new Date().toISOString();
+        await writeFile(this.filePath, JSON.stringify(data, null, 2));
+    }
+    /**
+     * Add entries to the changelog
+     */
+    async addEntries(entries) {
+        if (entries.length === 0)
+            return;
+        const data = await this.read();
+        data.entries.push(...entries);
+        await this.write(data);
+    }
+    /**
+     * Record a create action
+     */
+    async recordCreate(entityType, entityId, user) {
+        const entry = createChangelogEntry(entityType, entityId, 'create', { user });
+        await this.addEntries([entry]);
+        return entry;
+    }
+    /**
+     * Record a delete action
+     */
+    async recordDelete(entityType, entityId, user) {
+        const entry = createChangelogEntry(entityType, entityId, 'delete', { user });
+        await this.addEntries([entry]);
+        return entry;
+    }
+    /**
+     * Record an update action for a single field
+     */
+    async recordUpdate(entityType, entityId, field, oldValue, newValue, user) {
+        // Don't record if value didn't change
+        if (JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+            return null;
+        }
+        const entry = createChangelogEntry(entityType, entityId, 'update', {
+            field,
+            oldValue,
+            newValue,
+            user,
+        });
+        await this.addEntries([entry]);
+        return entry;
+    }
+    /**
+     * Record multiple field updates at once
+     */
+    async recordUpdates(entityType, entityId, changes, user) {
+        const entries = createUpdateEntries(entityType, entityId, changes, user);
+        await this.addEntries(entries);
+        return entries;
+    }
+    /**
+     * Query changelog entries
+     */
+    async query(options = {}) {
+        const data = await this.read();
+        return filterChangelogEntries(data.entries, options);
+    }
+    /**
+     * Get history for a specific entity
+     */
+    async getEntityHistory(entityId) {
+        return this.query({ entityId });
+    }
+    /**
+     * Get all entries (with optional pagination)
+     */
+    async getAll(limit, offset) {
+        const data = await this.read();
+        const total = data.entries.length;
+        const entries = filterChangelogEntries(data.entries, { limit, offset });
+        return { entries, total };
+    }
+    /**
+     * Get entries since a specific date
+     */
+    async getSince(since) {
+        return this.query({ since });
+    }
+    /**
+     * Get changelog summary statistics
+     */
+    async getStats() {
+        const data = await this.read();
+        const entries = data.entries;
+        const now = new Date();
+        const oneDayAgo = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+        const oneWeekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const oneMonthAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+        const byEntityType = {};
+        const byAction = {};
+        let last24h = 0;
+        let last7d = 0;
+        let last30d = 0;
+        for (const entry of entries) {
+            // Count by entity type
+            byEntityType[entry.entityType] = (byEntityType[entry.entityType] || 0) + 1;
+            // Count by action
+            byAction[entry.action] = (byAction[entry.action] || 0) + 1;
+            // Count recent activity
+            const entryDate = new Date(entry.timestamp);
+            if (entryDate >= oneDayAgo)
+                last24h++;
+            if (entryDate >= oneWeekAgo)
+                last7d++;
+            if (entryDate >= oneMonthAgo)
+                last30d++;
+        }
+        return {
+            totalEntries: entries.length,
+            byEntityType,
+            byAction,
+            recentActivity: { last24h, last7d, last30d },
+        };
+    }
+    /**
+     * Clear all changelog entries (use with caution)
+     */
+    async clear() {
+        await this.write({
+            version: '1.0',
+            lastUpdated: new Date().toISOString(),
+            entries: [],
+        });
+    }
+}
+// Singleton instance for convenience
+let defaultService = null;
+/**
+ * Get the default changelog service instance
+ */
+export function getChangelogService() {
+    if (!defaultService) {
+        defaultService = new ChangelogService();
+    }
+    return defaultService;
+}
+/**
+ * Reset the default service (mainly for testing)
+ */
+export function resetChangelogService() {
+    defaultService = null;
+}
+//# sourceMappingURL=changelog-service.js.map

package/dist/core/changelog.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+/**
+ * Entity types that can be tracked in the changelog
+ */
+export declare const ChangelogEntityType: z.ZodEnum<{
+    epic: "epic";
+    feature: "feature";
+    milestone: "milestone";
+    story: "story";
+}>;
+export type ChangelogEntityType = z.infer<typeof ChangelogEntityType>;
+/**
+ * Action types for changelog entries
+ */
+export declare const ChangelogAction: z.ZodEnum<{
+    create: "create";
+    update: "update";
+    delete: "delete";
+}>;
+export type ChangelogAction = z.infer<typeof ChangelogAction>;
+/**
+ * Schema for a single changelog entry
+ */
+export declare const ChangelogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodString;
+    entityType: z.ZodEnum<{
+        epic: "epic";
+        feature: "feature";
+        milestone: "milestone";
+        story: "story";
+    }>;
+    entityId: z.ZodString;
+    action: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        delete: "delete";
+    }>;
+    field: z.ZodOptional<z.ZodString>;
+    oldValue: z.ZodOptional<z.ZodUnknown>;
+    newValue: z.ZodOptional<z.ZodUnknown>;
+    user: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChangelogEntry = z.infer<typeof ChangelogEntrySchema>;
+/**
+ * Schema for the changelog file structure
+ */
+export declare const ChangelogFileSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodString>;
+    lastUpdated: z.ZodOptional<z.ZodString>;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        timestamp: z.ZodString;
+        entityType: z.ZodEnum<{
+            epic: "epic";
+            feature: "feature";
+            milestone: "milestone";
+            story: "story";
+        }>;
+        entityId: z.ZodString;
+        action: z.ZodEnum<{
+            create: "create";
+            update: "update";
+            delete: "delete";
+        }>;
+        field: z.ZodOptional<z.ZodString>;
+        oldValue: z.ZodOptional<z.ZodUnknown>;
+        newValue: z.ZodOptional<z.ZodUnknown>;
+        user: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChangelogFile = z.infer<typeof ChangelogFileSchema>;
+/**
+ * Options for querying changelog entries
+ */
+export interface ChangelogQueryOptions {
+    entityId?: string;
+    entityType?: ChangelogEntityType;
+    action?: ChangelogAction;
+    since?: string;
+    until?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Generate a unique ID for a changelog entry
+ */
+export declare function generateChangelogId(): string;
+/**
+ * Create a new changelog entry
+ */
+export declare function createChangelogEntry(entityType: ChangelogEntityType, entityId: string, action: ChangelogAction, options?: {
+    field?: string;
+    oldValue?: unknown;
+    newValue?: unknown;
+    user?: string;
+}): ChangelogEntry;
+/**
+ * Create multiple changelog entries for a batch of field updates
+ */
+export declare function createUpdateEntries(entityType: ChangelogEntityType, entityId: string, changes: Record<string, {
+    oldValue: unknown;
+    newValue: unknown;
+}>, user?: string): ChangelogEntry[];
+/**
+ * Filter changelog entries based on query options
+ */
+export declare function filterChangelogEntries(entries: ChangelogEntry[], options: ChangelogQueryOptions): ChangelogEntry[];
+/**
+ * Format a changelog entry for display
+ */
+export declare function formatChangelogEntry(entry: ChangelogEntry): string;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/core/changelog.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+/**
+ * Entity types that can be tracked in the changelog
+ */
+export const ChangelogEntityType = z.enum(['epic', 'feature', 'milestone', 'story']);
+/**
+ * Action types for changelog entries
+ */
+export const ChangelogAction = z.enum(['create', 'update', 'delete']);
+/**
+ * Schema for a single changelog entry
+ */
+export const ChangelogEntrySchema = z.object({
+    id: z.string(),
+    timestamp: z.string(), // ISO datetime
+    entityType: ChangelogEntityType,
+    entityId: z.string(),
+    action: ChangelogAction,
+    field: z.string().optional(),
+    oldValue: z.unknown().optional(),
+    newValue: z.unknown().optional(),
+    user: z.string().optional(),
+});
+/**
+ * Schema for the changelog file structure
+ */
+export const ChangelogFileSchema = z.object({
+    version: z.string().default('1.0'),
+    lastUpdated: z.string().optional(),
+    entries: z.array(ChangelogEntrySchema),
+});
+/**
+ * Generate a unique ID for a changelog entry
+ */
+export function generateChangelogId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `CHG-${timestamp}-${random}`;
+}
+/**
+ * Create a new changelog entry
+ */
+export function createChangelogEntry(entityType, entityId, action, options) {
+    return ChangelogEntrySchema.parse({
+        id: generateChangelogId(),
+        timestamp: new Date().toISOString(),
+        entityType,
+        entityId,
+        action,
+        field: options?.field,
+        oldValue: options?.oldValue,
+        newValue: options?.newValue,
+        user: options?.user,
+    });
+}
+/**
+ * Create multiple changelog entries for a batch of field updates
+ */
+export function createUpdateEntries(entityType, entityId, changes, user) {
+    const entries = [];
+    const timestamp = new Date().toISOString();
+    for (const [field, { oldValue, newValue }] of Object.entries(changes)) {
+        // Only create entry if value actually changed
+        if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
+            entries.push(ChangelogEntrySchema.parse({
+                id: generateChangelogId(),
+                timestamp,
+                entityType,
+                entityId,
+                action: 'update',
+                field,
+                oldValue,
+                newValue,
+                user,
+            }));
+        }
+    }
+    return entries;
+}
+/**
+ * Filter changelog entries based on query options
+ */
+export function filterChangelogEntries(entries, options) {
+    let filtered = [...entries];
+    if (options.entityId) {
+        filtered = filtered.filter(e => e.entityId === options.entityId);
+    }
+    if (options.entityType) {
+        filtered = filtered.filter(e => e.entityType === options.entityType);
+    }
+    if (options.action) {
+        filtered = filtered.filter(e => e.action === options.action);
+    }
+    if (options.since) {
+        const sinceDate = new Date(options.since);
+        filtered = filtered.filter(e => new Date(e.timestamp) >= sinceDate);
+    }
+    if (options.until) {
+        const untilDate = new Date(options.until);
+        filtered = filtered.filter(e => new Date(e.timestamp) <= untilDate);
+    }
+    // Sort by timestamp descending (newest first)
+    filtered.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    // Apply pagination
+    if (options.offset) {
+        filtered = filtered.slice(options.offset);
+    }
+    if (options.limit) {
+        filtered = filtered.slice(0, options.limit);
+    }
+    return filtered;
+}
+/**
+ * Format a changelog entry for display
+ */
+export function formatChangelogEntry(entry) {
+    const timestamp = new Date(entry.timestamp).toLocaleString();
+    const user = entry.user ? ` by ${entry.user}` : '';
+    switch (entry.action) {
+        case 'create':
+            return `[${timestamp}] Created ${entry.entityType} ${entry.entityId}${user}`;
+        case 'delete':
+            return `[${timestamp}] Deleted ${entry.entityType} ${entry.entityId}${user}`;
+        case 'update':
+            if (entry.field) {
+                const oldVal = formatValue(entry.oldValue);
+                const newVal = formatValue(entry.newValue);
+                return `[${timestamp}] Updated ${entry.entityType} ${entry.entityId} - ${entry.field}: ${oldVal} → ${newVal}${user}`;
+            }
+            return `[${timestamp}] Updated ${entry.entityType} ${entry.entityId}${user}`;
+        default:
+            return `[${timestamp}] ${entry.action} ${entry.entityType} ${entry.entityId}${user}`;
+    }
+}
+/**
+ * Format a value for display
+ */
+function formatValue(value) {
+    if (value === undefined || value === null) {
+        return '(empty)';
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+//# sourceMappingURL=changelog.js.map