structured-context 0.9.0

package/dist/integrations/miro/cache.d.ts

@@ -0,0 +1,21 @@
+import type { SpaceNode } from '../../types';
+export interface CachedNode {
+    miroCardId: string;
+    contentHash: string;
+}
+export interface CachedConnector {
+    miroConnectorId: string;
+}
+export interface SyncCache {
+    boardId: string;
+    frameId: string;
+    spaceName?: string;
+    lastSync: string;
+    nodes: Record<string, CachedNode>;
+    connectors: Record<string, CachedConnector>;
+}
+export declare function loadCache(boardId: string, frameId: string): SyncCache;
+export declare function saveCache(cache: SyncCache): void;
+export declare function computeNodeHash(node: SpaceNode): string;
+/** Compute hash from Miro card data (title + description) to compare against node hash */
+export declare function computeMiroCardHash(title: string, description: string): string;

package/dist/integrations/miro/cache.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const CACHE_DIR = '.miro-cache';
+function cachePath(boardId, frameId) {
+    return join(CACHE_DIR, `${boardId}-${frameId}.json`);
+}
+export function loadCache(boardId, frameId) {
+    const path = cachePath(boardId, frameId);
+    if (existsSync(path)) {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    return {
+        boardId,
+        frameId,
+        lastSync: '',
+        nodes: {},
+        connectors: {},
+    };
+}
+export function saveCache(cache) {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    const path = cachePath(cache.boardId, cache.frameId);
+    writeFileSync(path, `${JSON.stringify(cache, null, 2)}\n`);
+}
+export function computeNodeHash(node) {
+    const relevant = {
+        title: node.schemaData.title,
+        type: node.schemaData.type,
+        status: node.schemaData.status,
+        summary: node.schemaData.summary,
+        priority: node.schemaData.priority,
+        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.title),
+    };
+    return createHash('sha256').update(JSON.stringify(relevant)).digest('hex').slice(0, 16);
+}
+/** Normalize HTML entities in text (e.g., & → &) */
+function normalizeHtmlEntities(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCharCode(parseInt(dec, 10)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/** Compute hash from Miro card data (title + description) to compare against node hash */
+export function computeMiroCardHash(title, description) {
+    const normalized = {
+        title: normalizeHtmlEntities(title),
+        description: normalizeHtmlEntities(description),
+    };
+    return createHash('sha256').update(JSON.stringify(normalized)).digest('hex').slice(0, 16);
+}

package/dist/integrations/miro/client.d.ts

@@ -0,0 +1,99 @@
+export interface MiroCard {
+    id: string;
+    type: 'card';
+    data: {
+        title: string;
+        description?: string;
+    };
+    style?: {
+        cardTheme?: string;
+    };
+    position?: {
+        x: number;
+        y: number;
+    };
+    parent?: {
+        id: string;
+    };
+}
+export interface MiroConnector {
+    id: string;
+    type: 'connector';
+    startItem: {
+        id: string;
+    };
+    endItem: {
+        id: string;
+    };
+}
+export interface MiroFrame {
+    id: string;
+    type: 'frame';
+    data: {
+        title: string;
+    };
+}
+export declare class MiroClient {
+    private token;
+    private boardId;
+    constructor(boardId: string, token: string);
+    private request;
+    createCard(payload: {
+        data: {
+            title: string;
+            description?: string;
+        };
+        style?: {
+            cardTheme?: string;
+        };
+        position?: {
+            x: number;
+            y: number;
+            origin?: string;
+        };
+        parent?: {
+            id: string;
+        };
+        geometry?: {
+            width?: number;
+        };
+    }): Promise<MiroCard>;
+    updateCard(id: string, payload: {
+        data?: {
+            title?: string;
+            description?: string;
+        };
+        style?: {
+            cardTheme?: string;
+        };
+    }): Promise<MiroCard>;
+    getCard(id: string): Promise<MiroCard>;
+    createConnector(startId: string, endId: string, style?: {
+        strokeColor?: string;
+        strokeStyle?: string;
+        strokeWidth?: string;
+    }): Promise<MiroConnector>;
+    getConnectors(): Promise<MiroConnector[]>;
+    deleteConnector(id: string): Promise<void>;
+    createFrame(payload: {
+        data: {
+            title: string;
+            type?: string;
+        };
+        position?: {
+            x: number;
+            y: number;
+            origin?: string;
+        };
+        geometry?: {
+            width?: number;
+            height?: number;
+        };
+    }): Promise<MiroFrame>;
+    getFrames(): Promise<MiroFrame[]>;
+    getFrame(frameId: string): Promise<MiroFrame | undefined>;
+    getItemsInFrame(frameId: string): Promise<MiroCard[]>;
+}
+export declare class MiroNotFoundError extends Error {
+    constructor(message: string);
+}

package/dist/integrations/miro/client.js

@@ -0,0 +1,118 @@
+const API_BASE = 'https://api.miro.com/v2';
+const MAX_RETRIES = 3;
+export class MiroClient {
+    token;
+    boardId;
+    constructor(boardId, token) {
+        this.boardId = boardId;
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const url = `${API_BASE}/boards/${this.boardId}${path}`;
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            const res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    'Content-Type': 'application/json',
+                },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            if (res.status === 429) {
+                const retryAfter = parseInt(res.headers.get('Retry-After') ?? '2', 10);
+                if (attempt < MAX_RETRIES) {
+                    await new Promise((r) => setTimeout(r, retryAfter * 1000));
+                    continue;
+                }
+            }
+            if (res.status === 404) {
+                throw new MiroNotFoundError(`${method} ${path}: 404 Not Found`);
+            }
+            if (!res.ok) {
+                const text = await res.text();
+                lastError = new Error(`Miro API ${method} ${path}: ${res.status} ${text}`);
+                if (attempt < MAX_RETRIES && res.status >= 500) {
+                    await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+                    continue;
+                }
+                throw lastError;
+            }
+            if (res.status === 204)
+                return undefined;
+            return (await res.json());
+        }
+        throw lastError ?? new Error('Max retries exceeded');
+    }
+    // Cards
+    async createCard(payload) {
+        return this.request('POST', '/cards', payload);
+    }
+    async updateCard(id, payload) {
+        return this.request('PATCH', `/cards/${id}`, payload);
+    }
+    async getCard(id) {
+        return this.request('GET', `/cards/${id}`);
+    }
+    // Connectors
+    async createConnector(startId, endId, style) {
+        return this.request('POST', '/connectors', {
+            startItem: { id: startId, snapTo: 'auto' },
+            endItem: { id: endId, snapTo: 'auto' },
+            style,
+        });
+    }
+    async getConnectors() {
+        const items = [];
+        let cursor;
+        do {
+            const params = cursor ? `?cursor=${cursor}` : '';
+            const res = await this.request('GET', `/connectors${params}`);
+            items.push(...res.data);
+            cursor = res.cursor;
+        } while (cursor);
+        return items;
+    }
+    async deleteConnector(id) {
+        await this.request('DELETE', `/connectors/${id}`);
+    }
+    // Frames
+    async createFrame(payload) {
+        return this.request('POST', '/frames', payload);
+    }
+    async getFrames() {
+        const items = [];
+        let cursor;
+        do {
+            const params = cursor ? `?cursor=${cursor}` : '';
+            const res = await this.request('GET', `/frames${params}`);
+            items.push(...res.data);
+            cursor = res.cursor;
+        } while (cursor);
+        return items;
+    }
+    async getFrame(frameId) {
+        const frames = await this.getFrames();
+        return frames.find((f) => f.id === frameId);
+    }
+    // Items in frame
+    async getItemsInFrame(frameId) {
+        const items = [];
+        let cursor;
+        do {
+            const params = new URLSearchParams({ parent_item_id: frameId });
+            if (cursor)
+                params.set('cursor', cursor);
+            const res = await this.request('GET', `/items?${params}`);
+            items.push(...res.data);
+            cursor = res.cursor;
+        } while (cursor);
+        return items;
+    }
+}
+export class MiroNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MiroNotFoundError';
+    }
+}

package/dist/integrations/miro/layout.d.ts

@@ -0,0 +1,28 @@
+import type { HierarchyLevel, SpaceNode } from '../../types';
+export declare const CARD_WIDTH = 320;
+export interface LayoutResult {
+    positions: Map<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Bounding box of all cards (new + existing) — useful for sizing the containing frame. */
+    bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+}
+/**
+ * Compute positions for new cards only. Existing cards keep their Miro positions.
+ * New cards are laid out in rows grouped by OST type depth, starting below
+ * the lowest existing card (or at the origin if no existing cards).
+ *
+ * @param hierarchyLevels - Hierarchy levels from metadata. Depths are computed from level position.
+ *
+ * Returns positions and a bounding box covering all cards (for frame sizing).
+ */
+export declare function layoutNewCards(newNodes: SpaceNode[], existingPositions: Map<string, {
+    x: number;
+    y: number;
+}>, hierarchyLevels: HierarchyLevel[]): LayoutResult;

package/dist/integrations/miro/layout.js

@@ -0,0 +1,72 @@
+export const CARD_WIDTH = 320;
+const CARD_HEIGHT = 160;
+const H_GAP = 40;
+const V_GAP = 60;
+const FRAME_PADDING = 60;
+/**
+ * DEPRECATED - likely not needed after migration to render plugin and SpaceGraph
+ * Build a depth map from hierarchy levels.
+ * The position in the hierarchy array determines the depth.
+ */
+function buildDepthMap(hierarchyLevels) {
+    const depthMap = new Map();
+    for (const [i, level] of hierarchyLevels.entries()) {
+        depthMap.set(level.type, i);
+    }
+    return depthMap;
+}
+/**
+ * Compute positions for new cards only. Existing cards keep their Miro positions.
+ * New cards are laid out in rows grouped by OST type depth, starting below
+ * the lowest existing card (or at the origin if no existing cards).
+ *
+ * @param hierarchyLevels - Hierarchy levels from metadata. Depths are computed from level position.
+ *
+ * Returns positions and a bounding box covering all cards (for frame sizing).
+ */
+export function layoutNewCards(newNodes, existingPositions, hierarchyLevels) {
+    // Build depth map from hierarchy levels (position in hierarchy = depth)
+    const depthMap = buildDepthMap(hierarchyLevels);
+    // Find the lowest y among existing cards
+    let lowestY = 0;
+    for (const pos of existingPositions.values()) {
+        if (pos.y + CARD_HEIGHT / 2 > lowestY) {
+            lowestY = pos.y + CARD_HEIGHT / 2;
+        }
+    }
+    const startY = existingPositions.size > 0 ? lowestY + V_GAP * 2 : 0;
+    // Group new nodes by depth
+    const byDepth = new Map();
+    for (const node of newNodes) {
+        const depth = depthMap.get(node.schemaData.type) ?? depthMap.size;
+        if (!byDepth.has(depth))
+            byDepth.set(depth, []);
+        byDepth.get(depth)?.push(node);
+    }
+    const positions = new Map();
+    const depths = [...byDepth.keys()].sort((a, b) => a - b);
+    let rowY = startY;
+    for (const depth of depths) {
+        const nodes = byDepth.get(depth);
+        const totalWidth = nodes.length * CARD_WIDTH + (nodes.length - 1) * H_GAP;
+        let x = -totalWidth / 2 + CARD_WIDTH / 2;
+        for (const node of nodes) {
+            const title = node.title;
+            positions.set(title, { x, y: rowY });
+            x += CARD_WIDTH + H_GAP;
+        }
+        rowY += CARD_HEIGHT + V_GAP;
+    }
+    // Compute bounding box across all card positions (existing + new)
+    const allPositions = [...existingPositions.values(), ...positions.values()];
+    if (allPositions.length === 0) {
+        return { positions, bounds: { minX: 0, minY: 0, maxX: 0, maxY: 0 } };
+    }
+    const bounds = {
+        minX: Math.min(...allPositions.map((p) => p.x - CARD_WIDTH / 2)) - FRAME_PADDING,
+        minY: Math.min(...allPositions.map((p) => p.y - CARD_HEIGHT / 2)) - FRAME_PADDING,
+        maxX: Math.max(...allPositions.map((p) => p.x + CARD_WIDTH / 2)) + FRAME_PADDING,
+        maxY: Math.max(...allPositions.map((p) => p.y + CARD_HEIGHT / 2)) + FRAME_PADDING,
+    };
+    return { positions, bounds };
+}

package/dist/integrations/miro/styles.d.ts

@@ -0,0 +1,11 @@
+import type { HierarchyLevel, SpaceNode } from '../../types';
+/**
+ * Get card color based on type and hierarchy levels.
+ * Colors are assigned from palette based on level position.
+ *
+ * @param type - The node's type string
+ * @param hierarchyLevels - Hierarchy levels from metadata
+ */
+export declare function getCardColor(type: string, hierarchyLevels: HierarchyLevel[]): string;
+export declare function buildCardTitle(node: SpaceNode): string;
+export declare function buildCardDescription(node: SpaceNode): string;

package/dist/integrations/miro/styles.js

@@ -0,0 +1,65 @@
+// Color palette for hierarchy levels (distinct, visually appealing colors)
+const COLOR_PALETTE = [
+    '#ff9999', // Light red
+    '#99ccff', // Light blue
+    '#99ff99', // Light green
+    '#ffcc99', // Light orange
+    '#cc99ff', // Light purple
+    '#ffccff', // Light pink
+    '#ccffcc', // Pale mint
+    '#ffffcc', // Light yellow
+    '#ccccff', // Light indigo
+    '#ffcccc', // Pale red
+];
+const STATUS_ICONS = {
+    active: '*',
+    identified: '?',
+    wondering: '~',
+    exploring: '...',
+    paused: '||',
+    completed: 'ok',
+    archived: 'x',
+};
+/**
+ * Get card color based on type and hierarchy levels.
+ * Colors are assigned from palette based on level position.
+ *
+ * @param type - The node's type string
+ * @param hierarchyLevels - Hierarchy levels from metadata
+ */
+export function getCardColor(type, hierarchyLevels) {
+    // Find the level index for this type
+    const levelIndex = hierarchyLevels.findIndex((level) => level.type === type);
+    if (levelIndex >= 0) {
+        // Assign color from palette based on level position
+        const color = COLOR_PALETTE[levelIndex % COLOR_PALETTE.length];
+        if (color)
+            return color;
+    }
+    // Type not found in hierarchy - return default gray
+    return '#e0e0e0';
+}
+export function buildCardTitle(node) {
+    const title = node.title;
+    const status = node.schemaData.status;
+    const priority = node.schemaData.priority;
+    const icon = status ? (STATUS_ICONS[status] ?? status) : '';
+    const prefix = icon ? `[${icon}] ` : '';
+    const suffix = priority ? ` (${priority})` : '';
+    return `${prefix}${title}${suffix}`;
+}
+export function buildCardDescription(node) {
+    const parts = [];
+    const type = node.schemaData.type;
+    const status = node.schemaData.status;
+    parts.push(`Type: ${type}`);
+    if (status)
+        parts.push(`Status: ${status}`);
+    const summary = node.schemaData.summary;
+    if (summary)
+        parts.push(`\n${summary}`);
+    const content = node.schemaData.content;
+    if (content)
+        parts.push(`\n${content}`);
+    return parts.join('\n');
+}

package/dist/integrations/miro/sync.d.ts

@@ -0,0 +1,8 @@
+import type { SpaceContext } from '../../types';
+interface SyncOptions {
+    newFrame?: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export declare function miroSync(context: SpaceContext, options: SyncOptions): Promise<void>;
+export {};