@planu/cli 4.13.0 → 5.0.0

package/dist/engine/webhook/event-handlers.js

@@ -1,89 +0,0 @@
-// engine/webhook/event-handlers.ts — Handles individual Lemon Squeezy webhook events.
-// Each handler receives parsed payload and applies the corresponding business logic.
-// ---------------------------------------------------------------------------
-// Individual event handlers
-// ---------------------------------------------------------------------------
-/**
- * Handles subscription_cancelled: the customer cancelled their subscription.
- * The tier should be reverted to free when the subscription period ends.
- */
-export function handleSubscriptionCancelled(payload) {
-    const attrs = payload.data.attributes;
-    const endsAt = attrs.ends_at ?? 'unknown date';
-    const productName = attrs.product_name ?? 'Planu subscription';
-    return {
-        success: true,
-        eventType: 'subscription_cancelled',
-        statusCode: 200,
-        message: [
-            `Subscription cancellation recorded: ${productName}`,
-            `Access continues until: ${endsAt}`,
-            'Tier will revert to free upon expiry.',
-        ].join(' | '),
-    };
-}
-/**
- * Handles subscription_updated: plan tier may have changed (upgrade/downgrade).
- */
-export function handleSubscriptionUpdated(payload) {
-    const attrs = payload.data.attributes;
-    const variantName = attrs.variant_name ?? 'unknown variant';
-    const status = attrs.status ?? 'unknown';
-    return {
-        success: true,
-        eventType: 'subscription_updated',
-        statusCode: 200,
-        message: [`Subscription updated: variant=${variantName}`, `status=${status}`].join(' | '),
-    };
-}
-/**
- * Handles license_key_created: a new license key was issued (after purchase).
- * This is informational — the user will activate the key via activate_license tool.
- */
-export function handleLicenseKeyCreated(payload) {
-    const attrs = payload.data.attributes;
-    const productName = attrs.product_name ?? 'Planu';
-    const userEmail = attrs.user_email ?? 'unknown';
-    return {
-        success: true,
-        eventType: 'license_key_created',
-        statusCode: 200,
-        message: [
-            `License key created for: ${productName}`,
-            `customer=${userEmail}`,
-            'Key can be activated using activate_license tool.',
-        ].join(' | '),
-    };
-}
-/**
- * Returns a generic "acknowledged" result for unhandled but recognised events.
- */
-export function handleUnknownEvent(eventType) {
-    return {
-        success: true,
-        eventType,
-        statusCode: 200,
-        message: `Event acknowledged (no handler): ${eventType}`,
-    };
-}
-// ---------------------------------------------------------------------------
-// Dispatcher
-// ---------------------------------------------------------------------------
-const HANDLERS = {
-    subscription_cancelled: handleSubscriptionCancelled,
-    subscription_updated: handleSubscriptionUpdated,
-    license_key_created: handleLicenseKeyCreated,
-};
-/**
- * Dispatches a parsed webhook payload to the appropriate event handler.
- * Unhandled but valid events are acknowledged with a 200 response.
- */
-export function dispatchWebhookEvent(payload) {
-    const eventType = payload.meta.event_name;
-    const handler = HANDLERS[eventType];
-    if (handler) {
-        return handler(payload);
-    }
-    return handleUnknownEvent(eventType);
-}
-//# sourceMappingURL=event-handlers.js.map

package/dist/engine/webhook/index.d.ts

@@ -1,4 +0,0 @@
-export { startWebhookServer, stopWebhookServer, getWebhookState, setWebhookSecret, } from './server.js';
-export { validateSignature, extractSignatureHeader } from './signature.js';
-export { dispatchWebhookEvent, handleSubscriptionCancelled, handleSubscriptionUpdated, handleLicenseKeyCreated, handleUnknownEvent, } from './event-handlers.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/engine/webhook/index.js

@@ -1,5 +0,0 @@
-// engine/webhook/index.ts — Barrel re-export for the webhook engine module.
-export { startWebhookServer, stopWebhookServer, getWebhookState, setWebhookSecret, } from './server.js';
-export { validateSignature, extractSignatureHeader } from './signature.js';
-export { dispatchWebhookEvent, handleSubscriptionCancelled, handleSubscriptionUpdated, handleLicenseKeyCreated, handleUnknownEvent, } from './event-handlers.js';
-//# sourceMappingURL=index.js.map

package/dist/engine/webhook/server.d.ts

@@ -1,12 +0,0 @@
-import type { WebhookServerState } from '../../types/index.js';
-/** Returns the current webhook server state (immutable snapshot). */
-export declare function getWebhookState(): WebhookServerState;
-/** Replaces the webhook secret used for HMAC-SHA256 validation. */
-export declare function setWebhookSecret(secret: string): void;
-/** Starts the HTTP webhook server on the given port. Idempotent. */
-export declare function startWebhookServer(port?: number): Promise<WebhookServerState>;
-/** Stops the running webhook server gracefully. Idempotent. */
-export declare function stopWebhookServer(): Promise<WebhookServerState>;
-/** Reset replay protection state (for testing only). */
-export declare function _resetReplayState(): void;
-//# sourceMappingURL=server.d.ts.map

package/dist/engine/webhook/server.js

@@ -1,249 +0,0 @@
-// engine/webhook/server.ts — Lightweight HTTP webhook receiver using node:http.
-// No framework dependencies — only built-in Node.js modules.
-import { createServer } from 'node:http';
-import { randomUUID, createHash } from 'node:crypto';
-import { validateSignature, extractSignatureHeader } from './signature.js';
-import { dispatchWebhookEvent } from './event-handlers.js';
-// Constants
-const DEFAULT_PORT = 2358;
-const MAX_RECENT_EVENTS = 20;
-const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
-const NONCE_CACHE_SIZE = 1000;
-const MAX_TIMESTAMP_AGE_MS = 5 * 60 * 1000; // 5 minutes
-const RATE_LIMIT_WINDOW_MS = 60 * 1000;
-const RATE_LIMIT_MAX = 10;
-// Module state
-let activeServer = null;
-let serverState = makeIdleState();
-let webhookSecret = '';
-const recentNonces = new Set();
-const nonceQueue = [];
-const rateLimitMap = new Map();
-// Public API
-/** Returns the current webhook server state (immutable snapshot). */
-export function getWebhookState() {
-    return serverState;
-}
-/** Replaces the webhook secret used for HMAC-SHA256 validation. */
-export function setWebhookSecret(secret) {
-    webhookSecret = secret;
-}
-/** Starts the HTTP webhook server on the given port. Idempotent. */
-export async function startWebhookServer(port = DEFAULT_PORT) {
-    if (activeServer !== null) {
-        return serverState;
-    }
-    return new Promise((resolve, reject) => {
-        const server = createServer(handleRequest);
-        server.on('error', (err) => {
-            reject(err);
-        });
-        server.listen(port, () => {
-            activeServer = server;
-            serverState = {
-                running: true,
-                port,
-                startedAt: new Date().toISOString(),
-                eventsProcessed: 0,
-                recentEvents: [],
-            };
-            if (!webhookSecret) {
-                console.warn('[Planu] Warning: Webhook server started without a secret. All incoming requests will be accepted without signature verification. Set a secret via configure_webhook.');
-            }
-            resolve(serverState);
-        });
-    });
-}
-/** Stops the running webhook server gracefully. Idempotent. */
-export async function stopWebhookServer() {
-    if (activeServer === null) {
-        serverState = makeIdleState();
-        return serverState;
-    }
-    const server = activeServer;
-    return new Promise((resolve, reject) => {
-        server.close((err) => {
-            /* v8 ignore start */
-            if (err) {
-                reject(err);
-                return;
-            }
-            /* v8 ignore stop */
-            activeServer = null;
-            serverState = makeIdleState();
-            resolve(serverState);
-        });
-    });
-}
-// HTTP request handler
-function handleRequest(req, res) {
-    if (req.method !== 'POST') {
-        res.writeHead(405, { 'Content-Type': 'text/plain' });
-        res.end('Method Not Allowed');
-        return;
-    }
-    collectBody(req)
-        .then((rawBody) => {
-        processWebhookRequest(rawBody, req.headers, res);
-    })
-        .catch(() => {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        res.end('Bad Request');
-    });
-}
-function collectBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let totalSize = 0;
-        req.on('data', (chunk) => {
-            totalSize += chunk.length;
-            if (totalSize > MAX_BODY_SIZE) {
-                reject(new Error('Payload too large'));
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => {
-            resolve(Buffer.concat(chunks));
-        });
-        req.on('error', reject);
-    });
-}
-// Replay & rate-limit protection (SPEC-094 AC-7)
-function isReplayAttack(headers, bodyStr) {
-    const tsHeader = headers['x-webhook-timestamp'] ?? headers['X-Webhook-Timestamp'];
-    const timestamp = typeof tsHeader === 'string' ? tsHeader : undefined;
-    if (timestamp) {
-        const age = Date.now() - new Date(timestamp).getTime();
-        if (age > MAX_TIMESTAMP_AGE_MS || age < -MAX_TIMESTAMP_AGE_MS) {
-            return 'Webhook timestamp too old or in the future';
-        }
-    }
-    const nonce = extractNonce(headers, bodyStr);
-    if (nonce && recentNonces.has(nonce)) {
-        return 'Duplicate webhook (replay detected)';
-    }
-    if (nonce) {
-        trackNonce(nonce);
-    }
-    return null;
-}
-function extractNonce(headers, bodyStr) {
-    const idHeader = headers['x-webhook-id'] ?? headers['X-Webhook-Id'];
-    if (typeof idHeader === 'string') {
-        return idHeader;
-    }
-    return createHash('sha256').update(bodyStr).digest('hex').slice(0, 32);
-}
-function trackNonce(nonce) {
-    recentNonces.add(nonce);
-    nonceQueue.push(nonce);
-    while (nonceQueue.length > NONCE_CACHE_SIZE) {
-        const old = nonceQueue.shift();
-        if (old) {
-            recentNonces.delete(old);
-        }
-    }
-}
-function isRateLimited(source) {
-    const now = Date.now();
-    const entry = rateLimitMap.get(source);
-    if (!entry || now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
-        rateLimitMap.set(source, { count: 1, windowStart: now });
-        return false;
-    }
-    entry.count++;
-    return entry.count > RATE_LIMIT_MAX;
-}
-/** Reset replay protection state (for testing only). */
-export function _resetReplayState() {
-    recentNonces.clear();
-    nonceQueue.length = 0;
-    rateLimitMap.clear();
-}
-function processWebhookRequest(rawBody, headers, res) {
-    // Rate limiting
-    const source = String(headers['x-forwarded-for'] ?? headers['x-real-ip'] ?? 'unknown');
-    if (isRateLimited(source)) {
-        res.writeHead(429, { 'Content-Type': 'text/plain' });
-        res.end('Too Many Requests');
-        return;
-    }
-    // Replay protection
-    const replayReason = isReplayAttack(headers, rawBody.toString('utf8'));
-    if (replayReason) {
-        recordEvent('replay_rejected', false, replayReason, '');
-        res.writeHead(409, { 'Content-Type': 'text/plain' });
-        res.end(replayReason);
-        return;
-    }
-    // Signature validation (only if a secret is configured)
-    if (webhookSecret) {
-        const sig = extractSignatureHeader(headers);
-        if (!validateSignature(rawBody, sig, webhookSecret)) {
-            recordEvent('signature_invalid', false, 'Signature validation failed', '');
-            res.writeHead(401, { 'Content-Type': 'text/plain' });
-            res.end('Unauthorized');
-            return;
-        }
-    }
-    // Parse JSON body
-    let payload;
-    try {
-        payload = JSON.parse(rawBody.toString('utf8'));
-    }
-    catch {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        res.end('Invalid JSON');
-        return;
-    }
-    if (!payload.meta?.event_name) {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        res.end('Invalid payload: missing meta.event_name');
-        return;
-    }
-    // Dispatch event
-    const eventType = payload.meta.event_name;
-    try {
-        const result = dispatchWebhookEvent(payload);
-        recordEvent(eventType, result.success, result.message, result.eventType);
-        res.writeHead(result.statusCode, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ ok: true, message: result.message }));
-        /* v8 ignore start */
-    }
-    catch (err) {
-        const errMsg = err instanceof Error ? err.message : 'Unknown error';
-        recordEvent(eventType, false, errMsg, eventType);
-        res.writeHead(500, { 'Content-Type': 'text/plain' });
-        res.end('Internal Server Error');
-    }
-    /* v8 ignore stop */
-}
-// Event recording
-function recordEvent(_eventType, processed, summary, resolvedType) {
-    const record = {
-        id: randomUUID(),
-        eventType: resolvedType,
-        receivedAt: new Date().toISOString(),
-        processed,
-        summary,
-        ...(processed ? {} : { error: summary }),
-    };
-    const recentEvents = [record, ...serverState.recentEvents].slice(0, MAX_RECENT_EVENTS);
-    serverState = {
-        ...serverState,
-        eventsProcessed: serverState.eventsProcessed + 1,
-        recentEvents,
-    };
-}
-// Helpers
-function makeIdleState() {
-    return {
-        running: false,
-        port: DEFAULT_PORT,
-        startedAt: null,
-        eventsProcessed: 0,
-        recentEvents: [],
-    };
-}
-//# sourceMappingURL=server.js.map

package/dist/engine/webhook/signature.d.ts

@@ -1,16 +0,0 @@
-/**
- * Validates an HMAC-SHA256 signature from a Lemon Squeezy webhook request.
- * Uses timing-safe comparison to prevent timing attacks.
- *
- * @param rawBody - The raw request body bytes (NOT parsed JSON)
- * @param signatureHeader - The value of the X-Signature header
- * @param secret - The webhook secret configured in Lemon Squeezy dashboard
- * @returns true if signature is valid, false otherwise
- */
-export declare function validateSignature(rawBody: Buffer, signatureHeader: string, secret: string): boolean;
-/**
- * Extracts the signature header value from a map of HTTP headers.
- * Header names are case-insensitive in HTTP/1.1.
- */
-export declare function extractSignatureHeader(headers: Record<string, string | string[] | undefined>): string;
-//# sourceMappingURL=signature.d.ts.map

package/dist/engine/webhook/signature.js

@@ -1,49 +0,0 @@
-// engine/webhook/signature.ts — HMAC-SHA256 signature validation for Lemon Squeezy webhooks.
-// Validates the X-Signature header against the raw request body.
-import { createHmac, timingSafeEqual } from 'node:crypto';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const SIGNATURE_HEADER = 'x-signature';
-const HMAC_ALGO = 'sha256';
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Validates an HMAC-SHA256 signature from a Lemon Squeezy webhook request.
- * Uses timing-safe comparison to prevent timing attacks.
- *
- * @param rawBody - The raw request body bytes (NOT parsed JSON)
- * @param signatureHeader - The value of the X-Signature header
- * @param secret - The webhook secret configured in Lemon Squeezy dashboard
- * @returns true if signature is valid, false otherwise
- */
-export function validateSignature(rawBody, signatureHeader, secret) {
-    if (!secret || !signatureHeader) {
-        return false;
-    }
-    const expectedHex = createHmac(HMAC_ALGO, secret).update(rawBody).digest('hex');
-    try {
-        const expectedBuf = Buffer.from(expectedHex, 'hex');
-        const receivedBuf = Buffer.from(signatureHeader, 'hex');
-        if (expectedBuf.length !== receivedBuf.length) {
-            return false;
-        }
-        return timingSafeEqual(expectedBuf, receivedBuf);
-    }
-    catch /* v8 ignore start */ {
-        return false;
-    } /* v8 ignore stop */
-}
-/**
- * Extracts the signature header value from a map of HTTP headers.
- * Header names are case-insensitive in HTTP/1.1.
- */
-export function extractSignatureHeader(headers) {
-    const raw = headers[SIGNATURE_HEADER];
-    if (Array.isArray(raw)) {
-        return raw[0] ?? '';
-    }
-    return raw ?? '';
-}
-//# sourceMappingURL=signature.js.map

package/dist/storage/data-dir-discovery.d.ts

@@ -1,31 +0,0 @@
-/** Clear the resolution cache — TEST USE ONLY. */
-export declare function clearDataDirCache(): void;
-/**
- * Resolve the data dir for `projectId`, walking ancestors of cwd and of the
- * registered projectPath when the cwd-relative dir lacks the anchor file.
- *
- * Result is cached per session: the first successful (or unsuccessful)
- * resolution sticks, so repeated reads do not pay the I/O cost.
- *
- * Returns null when no `knowledge.json` is found anywhere — callers should
- * treat that as "project not initialized in any reachable location".
- *
- * @param projectId Project hash identifier.
- * @param cwd       Optional working directory override (defaults to
- *                  `process.cwd()`). Exposed for tests, where Vitest workers
- *                  cannot mutate the real process cwd.
- */
-export declare function resolveProjectDataDir(projectId: string, cwd?: string): Promise<string | null>;
-/**
- * Discover an existing data file for `projectId`. Returns the absolute path
- * when the resolved data dir contains `<relative>`, or null otherwise.
- *
- * Anchored on `knowledge.json` — if no project owns the dir, no file is
- * returned even if a same-named file happens to live in another repo's
- * `data/projects/<id>/` tree.
- *
- * @param projectId Project hash identifier.
- * @param relative  Path under `data/projects/<id>/`, e.g. "specs.json".
- */
-export declare function discoverProjectDataFile(projectId: string, relative: string, cwd?: string): Promise<string | null>;
-//# sourceMappingURL=data-dir-discovery.d.ts.map

package/dist/storage/data-dir-discovery.js

@@ -1,140 +0,0 @@
-// data-dir-discovery.ts — Cwd-tolerant data dir discovery for project stores.
-//
-// Background: projectDataDir() returns a relative path "data/projects/<id>".
-// All store reads thus depend on process.cwd(). When the MCP server is launched
-// from a directory other than the one used at init_project time, stores cannot
-// see existing data on disk and report the project as missing.
-//
-// This module resolves the data dir for a projectId once per session by
-// walking up from cwd and from the registered projectPath, anchoring the
-// search on `knowledge.json` (the canonical signal that a directory truly
-// belongs to the given project — not just a co-located hash collision in an
-// unrelated repo). Once resolved, the same base dir is used for every store
-// (specs.json, knowledge.json, etc.) so they stay coherent.
-//
-// Reads are read-only and best-effort: writes still go through projectDataDir().
-import { stat } from 'node:fs/promises';
-import { join, dirname, isAbsolute } from 'node:path';
-import { getProjects } from './global-projects-store.js';
-const MAX_WALK_DEPTH = 8;
-/** The file used to anchor discovery: presence == this dir owns the project. */
-const ANCHOR_FILE = 'knowledge.json';
-const dataDirCache = new Map();
-/** Clear the resolution cache — TEST USE ONLY. */
-export function clearDataDirCache() {
-    dataDirCache.clear();
-}
-async function fileExists(filePath) {
-    try {
-        const s = await stat(filePath);
-        return s.isFile();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Walk upward from `startDir` looking for the first directory under which
- * `<dir>/<subPath>/<ANCHOR_FILE>` exists. Returns the matched data dir
- * (`<dir>/<subPath>`), or null when no anchor is found.
- */
-async function walkUpForAnchor(startDir, subPath) {
-    if (!isAbsolute(startDir)) {
-        return null;
-    }
-    let current = startDir;
-    for (let i = 0; i < MAX_WALK_DEPTH; i++) {
-        const dataDir = join(current, subPath);
-        if (await fileExists(join(dataDir, ANCHOR_FILE))) {
-            return dataDir;
-        }
-        const parent = dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
-    }
-    return null;
-}
-/**
- * Resolve the data dir for `projectId`, walking ancestors of cwd and of the
- * registered projectPath when the cwd-relative dir lacks the anchor file.
- *
- * Result is cached per session: the first successful (or unsuccessful)
- * resolution sticks, so repeated reads do not pay the I/O cost.
- *
- * Returns null when no `knowledge.json` is found anywhere — callers should
- * treat that as "project not initialized in any reachable location".
- *
- * @param projectId Project hash identifier.
- * @param cwd       Optional working directory override (defaults to
- *                  `process.cwd()`). Exposed for tests, where Vitest workers
- *                  cannot mutate the real process cwd.
- */
-export async function resolveProjectDataDir(projectId, cwd = process.cwd()) {
-    if (dataDirCache.has(projectId)) {
-        return dataDirCache.get(projectId) ?? null;
-    }
-    const subPath = join('data', 'projects', projectId);
-    // 1. cwd-relative direct hit (current behavior, fast path)
-    const direct = join(cwd, subPath);
-    if (await fileExists(join(direct, ANCHOR_FILE))) {
-        dataDirCache.set(projectId, direct);
-        return direct;
-    }
-    // 2. Walk up from cwd
-    const fromCwd = await walkUpForAnchor(cwd, subPath);
-    if (fromCwd !== null) {
-        dataDirCache.set(projectId, fromCwd);
-        return fromCwd;
-    }
-    // 3. Use the registered projectPath, if any
-    let registeredPath = null;
-    try {
-        const projects = await getProjects();
-        const match = projects.find((p) => p.hash === projectId);
-        if (match) {
-            registeredPath = match.path;
-        }
-    }
-    catch {
-        /* registry unreadable — skip */
-    }
-    if (registeredPath !== null) {
-        const directFromRegistered = join(registeredPath, subPath);
-        if (await fileExists(join(directFromRegistered, ANCHOR_FILE))) {
-            dataDirCache.set(projectId, directFromRegistered);
-            return directFromRegistered;
-        }
-        const fromRegistered = await walkUpForAnchor(registeredPath, subPath);
-        if (fromRegistered !== null) {
-            dataDirCache.set(projectId, fromRegistered);
-            return fromRegistered;
-        }
-    }
-    dataDirCache.set(projectId, null);
-    return null;
-}
-/**
- * Discover an existing data file for `projectId`. Returns the absolute path
- * when the resolved data dir contains `<relative>`, or null otherwise.
- *
- * Anchored on `knowledge.json` — if no project owns the dir, no file is
- * returned even if a same-named file happens to live in another repo's
- * `data/projects/<id>/` tree.
- *
- * @param projectId Project hash identifier.
- * @param relative  Path under `data/projects/<id>/`, e.g. "specs.json".
- */
-export async function discoverProjectDataFile(projectId, relative, cwd) {
-    const dir = await resolveProjectDataDir(projectId, cwd ?? process.cwd());
-    if (dir === null) {
-        return null;
-    }
-    const candidate = join(dir, relative);
-    if (await fileExists(candidate)) {
-        return candidate;
-    }
-    return null;
-}
-//# sourceMappingURL=data-dir-discovery.js.map

package/dist/storage/license-store.d.ts

@@ -1,6 +0,0 @@
-import type { LicenseState } from '../types/index.js';
-export declare function getLicenseState(): Promise<LicenseState | null>;
-export declare function saveLicenseState(state: LicenseState): Promise<void>;
-export declare function deleteLicenseState(): Promise<void>;
-export declare function countActiveProjects(): Promise<number>;
-//# sourceMappingURL=license-store.d.ts.map