sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/quotaThresholds.js

@@ -0,0 +1,85 @@
+/**
+ * Threshold-crossing detection for subscription quota windows.
+ *
+ * Pure and host-neutral: the VS Code extension and the CLI dashboard both
+ * feed it every quota sample and raise whatever alerts it returns, so a user
+ * hears "your five-hour window is at 80%" the same way in both. Alerts fire
+ * once per threshold per reset window, on the rising edge; when a window
+ * resets the memory resets with it.
+ *
+ * @module quotaThresholds
+ */
+/**
+ * Defaults tuned to the two surprises users report: the afternoon five-hour
+ * cutoff (warn at 80%, escalate at 95%) and the mid-week weekly cap (90%).
+ */
+export const DEFAULT_QUOTA_THRESHOLDS = {
+    fiveHour: [80, 95],
+    sevenDay: [90],
+};
+function sanitizeThresholds(values) {
+    return [...new Set(values.filter((v) => Number.isFinite(v) && v > 0 && v <= 100))].sort((a, b) => a - b);
+}
+function evaluateWindow(window, quota, thresholds, previous) {
+    const sorted = sanitizeThresholds(thresholds);
+    const utilization = Number.isFinite(quota.utilization) ? quota.utilization : 0;
+    const resetsAt = quota.resetsAt ?? '';
+    let level = 0;
+    for (const threshold of sorted)
+        if (utilization >= threshold)
+            level = threshold;
+    const previousLevel = previous && previous.resetsAt === resetsAt ? previous.level : 0;
+    const memory = { resetsAt, level: Math.max(level, previousLevel) };
+    if (level <= previousLevel)
+        return { alert: null, memory };
+    return {
+        alert: {
+            window,
+            threshold: level,
+            utilization,
+            resetsAt,
+            severity: level >= sorted[sorted.length - 1] ? 'critical' : 'warning',
+        },
+        memory,
+    };
+}
+/**
+ * Compare a quota sample against the thresholds and the alerts already
+ * raised. Unavailable samples produce no alerts and leave the memory alone.
+ */
+export function evaluateQuotaThresholds(quota, config = DEFAULT_QUOTA_THRESHOLDS, memory = {}) {
+    if (!quota.available)
+        return { alerts: [], memory };
+    const fiveHour = evaluateWindow('fiveHour', quota.fiveHour, config.fiveHour, memory.fiveHour);
+    const sevenDay = evaluateWindow('sevenDay', quota.sevenDay, config.sevenDay, memory.sevenDay);
+    return {
+        alerts: [fiveHour.alert, sevenDay.alert].filter((alert) => alert !== null),
+        memory: { fiveHour: fiveHour.memory, sevenDay: sevenDay.memory },
+    };
+}
+const WINDOW_LABELS = {
+    fiveHour: 'five-hour window',
+    sevenDay: 'seven-day window',
+};
+function formatResetTime(resetsAt, now) {
+    const ms = Date.parse(resetsAt);
+    if (!Number.isFinite(ms))
+        return null;
+    const reset = new Date(ms);
+    const sameDay = reset.getFullYear() === now.getFullYear() &&
+        reset.getMonth() === now.getMonth() &&
+        reset.getDate() === now.getDate();
+    return new Intl.DateTimeFormat(undefined, {
+        ...(sameDay ? {} : { weekday: 'short' }),
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    }).format(reset);
+}
+/** One-line, reset-aware message: `Claude five-hour window at 82% (resets 14:00)`. */
+export function describeQuotaThresholdAlert(alert, options = {}) {
+    const provider = options.providerLabel ?? 'Claude';
+    const reset = formatResetTime(alert.resetsAt, options.now ?? new Date());
+    const suffix = reset ? ` (resets ${reset})` : '';
+    return `${provider} ${WINDOW_LABELS[alert.window]} at ${Math.round(alert.utilization)}%${suffix}`;
+}

package/dist/esm/readers/decisions.js

@@ -0,0 +1,24 @@
+/**
+ * Reader for persisted decisions.
+ */
+import { readProjectJsonStore } from './helpers';
+export async function readDecisions(project, opts) {
+    const store = await readProjectJsonStore(project, 'decisions');
+    if (!store)
+        return [];
+    let decisions = store.decisions && typeof store.decisions === 'object' && !Array.isArray(store.decisions)
+        ? Object.values(store.decisions)
+        : [];
+    // Sort by timestamp descending
+    decisions.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    if (opts?.search) {
+        const q = opts.search.toLowerCase();
+        decisions = decisions.filter((d) => d.description.toLowerCase().includes(q) ||
+            d.rationale.toLowerCase().includes(q) ||
+            d.chosenOption.toLowerCase().includes(q));
+    }
+    if (opts?.limit && opts.limit > 0) {
+        decisions = decisions.slice(0, opts.limit);
+    }
+    return decisions;
+}

package/dist/esm/readers/handoff.js

@@ -0,0 +1,20 @@
+/**
+ * Reader for session handoff documents.
+ */
+import * as fs from 'fs';
+import { getProjectDataPath } from '../paths';
+export async function readLatestHandoff(project) {
+    const candidates = typeof project === 'string' ? [project] : project.candidates;
+    for (const slug of candidates) {
+        const filePath = getProjectDataPath(slug, 'handoffs').replace(/\.json$/, '-latest.md');
+        try {
+            const content = await fs.promises.readFile(filePath, 'utf-8');
+            if (content.trim())
+                return content.trim();
+        }
+        catch {
+            // Try the legacy candidate.
+        }
+    }
+    return null;
+}

package/dist/esm/readers/helpers.js

@@ -0,0 +1,27 @@
+/**
+ * Shared reader helpers.
+ */
+import * as fs from 'fs';
+import { getProjectDataPath } from '../paths';
+/**
+ * Reads and parses a JSON store file. Returns null if file missing or malformed.
+ */
+export async function readJsonStore(filePath) {
+    try {
+        const content = await fs.promises.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads the canonical project store, falling back to the legacy symlink slug. */
+export async function readProjectJsonStore(project, subdomain) {
+    const candidates = typeof project === 'string' ? [project] : project.candidates;
+    for (const slug of candidates) {
+        const store = await readJsonStore(getProjectDataPath(slug, subdomain));
+        if (store)
+            return store;
+    }
+    return null;
+}

package/dist/esm/readers/history.js

@@ -0,0 +1,9 @@
+/**
+ * Reader for historical data.
+ */
+import { getGlobalDataPath } from '../paths';
+import { readJsonStore } from './helpers';
+export async function readHistory() {
+    const filePath = getGlobalDataPath('historical-data.json');
+    return readJsonStore(filePath);
+}

package/dist/esm/readers/notes.js

@@ -0,0 +1,48 @@
+/**
+ * Reader for knowledge notes.
+ */
+import { readProjectJsonStore } from './helpers';
+export async function readNotes(project, opts) {
+    const store = await readProjectJsonStore(project, 'knowledge-notes');
+    if (!store)
+        return [];
+    let notes = [];
+    const notesByFile = store.notesByFile && typeof store.notesByFile === 'object' && !Array.isArray(store.notesByFile)
+        ? store.notesByFile
+        : {};
+    if (opts?.file) {
+        // Normalize file path for comparison
+        const normalizedFile = opts.file.replace(/\\/g, '/');
+        for (const [filePath, fileNotes] of Object.entries(notesByFile)) {
+            const normalizedKey = filePath.replace(/\\/g, '/');
+            if (normalizedKey === normalizedFile ||
+                normalizedKey.endsWith('/' + normalizedFile) ||
+                normalizedFile.endsWith('/' + normalizedKey)) {
+                if (Array.isArray(fileNotes))
+                    notes.push(...fileNotes);
+            }
+        }
+    }
+    else {
+        for (const fileNotes of Object.values(notesByFile)) {
+            if (Array.isArray(fileNotes))
+                notes.push(...fileNotes);
+        }
+    }
+    if (opts?.type) {
+        notes = notes.filter((n) => n.noteType === opts.type);
+    }
+    if (opts?.status) {
+        notes = notes.filter((n) => n.status === opts.status);
+    }
+    // Sort by importance then updatedAt
+    const importanceOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    notes.sort((a, b) => {
+        const ia = importanceOrder[a.importance] ?? 4;
+        const ib = importanceOrder[b.importance] ?? 4;
+        if (ia !== ib)
+            return ia - ib;
+        return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+    });
+    return notes;
+}

package/dist/esm/readers/plans.js

@@ -0,0 +1,225 @@
+/**
+ * Reader/writer for persisted plan history.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { PLAN_SCHEMA_VERSION, MAX_PLANS_PER_PROJECT } from '../types/plan';
+import { getProjectDataPath, encodeWorkspacePath } from '../paths';
+import { readJsonStore } from './helpers';
+import { parsePlanMarkdown } from '../parsers/planExtractor';
+import { atomicWriteJson } from '../writers/atomic';
+import { getClaudeProjectsDir, getLiveClaudeHome } from '../claudePaths';
+export async function readPlans(slug, opts) {
+    const filePath = getProjectDataPath(slug, 'plans');
+    const store = await readJsonStore(filePath);
+    if (!store)
+        return [];
+    let plans = Array.isArray(store.plans) ? [...store.plans] : [];
+    const status = opts?.status ?? 'all';
+    if (status !== 'all') {
+        plans = plans.filter((p) => p.status === status);
+    }
+    if (opts?.source) {
+        plans = plans.filter((p) => p.source === opts.source);
+    }
+    // Already sorted by createdAt desc in storage
+    if (opts?.limit && opts.limit > 0) {
+        plans = plans.slice(0, opts.limit);
+    }
+    return plans;
+}
+export async function getLatestPlan(slug) {
+    const plans = await readPlans(slug, { limit: 1 });
+    return plans[0] ?? null;
+}
+export function getPlanAnalytics(plans) {
+    const totalPlans = plans.length;
+    if (totalPlans === 0) {
+        return {
+            totalPlans: 0,
+            completedPlans: 0,
+            failedPlans: 0,
+            abandonedPlans: 0,
+            avgCompletionRate: 0,
+            avgDurationMs: 0,
+            avgStepsPerPlan: 0,
+            avgTokensPerPlan: 0,
+            avgCostPerPlan: 0,
+            plansBySource: {},
+            mostCommonFailureStep: null,
+            completionTrend: [],
+        };
+    }
+    const completedPlans = plans.filter((p) => p.status === 'completed').length;
+    const failedPlans = plans.filter((p) => p.status === 'failed').length;
+    const abandonedPlans = plans.filter((p) => p.status === 'abandoned').length;
+    const avgCompletionRate = plans.reduce((s, p) => s + p.completionRate, 0) / totalPlans;
+    const plansWithDuration = plans.filter((p) => p.totalDurationMs != null && p.totalDurationMs > 0);
+    const avgDurationMs = plansWithDuration.length > 0
+        ? plansWithDuration.reduce((s, p) => s + (p.totalDurationMs || 0), 0) /
+            plansWithDuration.length
+        : 0;
+    const avgStepsPerPlan = plans.reduce((s, p) => s + p.steps.length, 0) / totalPlans;
+    const plansWithTokens = plans.filter((p) => p.totalTokensUsed != null && p.totalTokensUsed > 0);
+    const avgTokensPerPlan = plansWithTokens.length > 0
+        ? plansWithTokens.reduce((s, p) => s + (p.totalTokensUsed || 0), 0) / plansWithTokens.length
+        : 0;
+    const plansWithCost = plans.filter((p) => p.totalCostUsd != null && p.totalCostUsd > 0);
+    const avgCostPerPlan = plansWithCost.length > 0
+        ? plansWithCost.reduce((s, p) => s + (p.totalCostUsd || 0), 0) / plansWithCost.length
+        : 0;
+    // Plans by source
+    const plansBySource = {};
+    for (const p of plans) {
+        plansBySource[p.source] = (plansBySource[p.source] || 0) + 1;
+    }
+    // Most common failure step (which step index fails most)
+    const failureCounts = new Map();
+    for (const p of plans) {
+        for (let i = 0; i < p.steps.length; i++) {
+            if (p.steps[i].status === 'failed') {
+                failureCounts.set(i, (failureCounts.get(i) || 0) + 1);
+            }
+        }
+    }
+    let mostCommonFailureStep = null;
+    if (failureCounts.size > 0) {
+        let maxCount = 0;
+        let maxIdx = 0;
+        for (const [idx, count] of failureCounts) {
+            if (count > maxCount) {
+                maxCount = count;
+                maxIdx = idx;
+            }
+        }
+        mostCommonFailureStep = `Step ${maxIdx + 1}`;
+    }
+    // Completion trend (grouped by date)
+    const byDate = new Map();
+    for (const p of plans) {
+        const date = p.createdAt.substring(0, 10); // YYYY-MM-DD
+        const existing = byDate.get(date) || { sum: 0, count: 0 };
+        existing.sum += p.completionRate;
+        existing.count += 1;
+        byDate.set(date, existing);
+    }
+    const completionTrend = Array.from(byDate.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([date, { sum, count }]) => ({ date, rate: sum / count }));
+    return {
+        totalPlans,
+        completedPlans,
+        failedPlans,
+        abandonedPlans,
+        avgCompletionRate,
+        avgDurationMs,
+        avgStepsPerPlan,
+        avgTokensPerPlan,
+        avgCostPerPlan,
+        plansBySource,
+        mostCommonFailureStep,
+        completionTrend,
+    };
+}
+export async function writePlans(slug, plans) {
+    const filePath = getProjectDataPath(slug, 'plans');
+    // Sort by createdAt desc and cap
+    const sorted = [...plans].sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    const capped = sorted.slice(0, MAX_PLANS_PER_PROJECT);
+    const store = {
+        schemaVersion: PLAN_SCHEMA_VERSION,
+        plans: capped,
+        lastSaved: new Date().toISOString(),
+    };
+    await atomicWriteJson(filePath, store);
+}
+/**
+ * Reads raw plan markdown files from ~/.claude/plans/ that belong to
+ * sessions in the given workspace. Maps session JSONL slugs to plan filenames.
+ */
+export async function readClaudeCodePlanFiles(workspacePath) {
+    const claudePlansDir = path.join(getLiveClaudeHome(), 'plans');
+    const claudeProjectsDir = getClaudeProjectsDir();
+    // Find the project directory in ~/.claude/projects/
+    const cwd = workspacePath || process.cwd();
+    const encoded = encodeWorkspacePath(path.resolve(cwd));
+    const projectDir = path.join(claudeProjectsDir, encoded);
+    if (!fs.existsSync(projectDir) || !fs.existsSync(claudePlansDir)) {
+        return [];
+    }
+    // Extract unique slugs from session JSONL files (read first match per file)
+    const slugSet = new Set();
+    let jsonlFiles;
+    try {
+        jsonlFiles = (await fs.promises.readdir(projectDir)).filter((f) => f.endsWith('.jsonl'));
+    }
+    catch {
+        return [];
+    }
+    // Read slugs in parallel (grep first "slug" field from each JSONL)
+    const SLUG_RE = /"slug":"([^"]+)"/;
+    await Promise.all(jsonlFiles.map(async (f) => {
+        try {
+            const filePath = path.join(projectDir, f);
+            const handle = await fs.promises.open(filePath, 'r');
+            try {
+                // Read first 32KB — slug is always in the first few lines
+                const buf = Buffer.alloc(32768);
+                const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+                const chunk = buf.toString('utf-8', 0, bytesRead);
+                for (const line of chunk.split('\n')) {
+                    const m = line.match(SLUG_RE);
+                    if (m) {
+                        slugSet.add(m[1]);
+                        break;
+                    }
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            /* skip unreadable files */
+        }
+    }));
+    if (slugSet.size === 0)
+        return [];
+    // Read matching plan files
+    const plans = [];
+    for (const slug of slugSet) {
+        const planPath = path.join(claudePlansDir, `${slug}.md`);
+        try {
+            const stat = await fs.promises.stat(planPath);
+            const content = await fs.promises.readFile(planPath, 'utf-8');
+            const parsed = parsePlanMarkdown(content);
+            const steps = parsed.steps.map((s) => ({
+                id: s.id,
+                description: s.description,
+                status: s.status,
+                phase: s.phase,
+                complexity: s.complexity,
+            }));
+            const completed = steps.filter((s) => s.status === 'completed').length;
+            const total = steps.length;
+            plans.push({
+                id: `claude-plan-${slug}`,
+                projectSlug: encoded,
+                sessionId: slug,
+                title: parsed.title || slug,
+                source: 'claude-code',
+                createdAt: stat.mtime.toISOString(),
+                status: total > 0 && completed === total ? 'completed' : 'in_progress',
+                steps,
+                completionRate: total > 0 ? completed / total : 0,
+                rawMarkdown: content,
+            });
+        }
+        catch {
+            /* plan file missing or unreadable */
+        }
+    }
+    // Sort by createdAt descending
+    plans.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return plans;
+}

package/dist/esm/readers/tasks.js

@@ -0,0 +1,19 @@
+/**
+ * Reader for persisted tasks.
+ */
+import { readProjectJsonStore } from './helpers';
+export async function readTasks(project, opts) {
+    const store = await readProjectJsonStore(project, 'tasks');
+    if (!store)
+        return [];
+    let tasks = store.tasks && typeof store.tasks === 'object' && !Array.isArray(store.tasks)
+        ? Object.values(store.tasks)
+        : [];
+    const status = opts?.status ?? 'all';
+    if (status !== 'all') {
+        tasks = tasks.filter((t) => t.status === status);
+    }
+    // Sort by updatedAt descending
+    tasks.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    return tasks;
+}