optimal-cli 0.1.0

package/dist/lib/budget/scenarios.js

@@ -0,0 +1,214 @@
+/**
+ * Budget scenario manager — save, load, list, compare, and delete named scenarios.
+ *
+ * Scenarios are stored as JSON files on disk at:
+ *   /home/optimal/optimal-cli/data/scenarios/{name}.json
+ *
+ * Each scenario captures a full snapshot of projected units after applying
+ * a uniform adjustment to the live fpa_wes_imports data.
+ */
+import 'dotenv/config';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchWesImports, initializeProjections, applyUniformAdjustment, calculateTotals, } from './projections.js';
+// --- Directory resolution ---
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Resolve relative to the repo root (lib/budget/ -> ../../data/scenarios/)
+const SCENARIOS_DIR = join(__dirname, '..', '..', 'data', 'scenarios');
+function ensureScenariosDir() {
+    mkdirSync(SCENARIOS_DIR, { recursive: true });
+}
+// --- Helpers ---
+/**
+ * Sanitize a scenario name into a safe filename segment.
+ * Lowercases, replaces spaces and disallowed chars with hyphens,
+ * collapses repeated hyphens, and strips leading/trailing hyphens.
+ */
+function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function scenarioPath(sanitized) {
+    return join(SCENARIOS_DIR, `${sanitized}.json`);
+}
+// --- Public API ---
+/**
+ * Save current projections as a named scenario to disk.
+ *
+ * Fetches live data via fetchWesImports, applies the given adjustment,
+ * calculates totals, and writes the result as JSON.
+ *
+ * @returns The absolute path to the saved scenario file.
+ */
+export async function saveScenario(opts) {
+    ensureScenariosDir();
+    const sanitized = sanitizeName(opts.name);
+    if (!sanitized) {
+        throw new Error(`Invalid scenario name: "${opts.name}"`);
+    }
+    // Fetch and process data
+    const summary = await fetchWesImports({
+        fiscalYear: opts.fiscalYear,
+        userId: opts.userId,
+    });
+    const initialized = initializeProjections(summary);
+    const adjusted = applyUniformAdjustment(initialized, opts.adjustmentType, opts.adjustmentValue);
+    const totals = calculateTotals(adjusted);
+    const scenarioData = {
+        name: opts.name,
+        createdAt: new Date().toISOString(),
+        adjustmentType: opts.adjustmentType,
+        adjustmentValue: opts.adjustmentValue,
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
+        projections: adjusted.map((p) => ({
+            programCode: p.programCode,
+            masterProgram: p.masterProgram,
+            actualUnits: p.actualUnits,
+            projectedUnits: p.projectedUnits,
+        })),
+        totals: {
+            totalActual: totals.totalActual,
+            totalProjected: totals.totalProjected,
+            percentageChange: totals.percentageChange,
+        },
+    };
+    const filePath = scenarioPath(sanitized);
+    writeFileSync(filePath, JSON.stringify(scenarioData, null, 2), 'utf-8');
+    return filePath;
+}
+/**
+ * Load a saved scenario from disk by name.
+ *
+ * Accepts the original name (will be sanitized) or the sanitized form.
+ */
+export async function loadScenario(name) {
+    const sanitized = sanitizeName(name);
+    const filePath = scenarioPath(sanitized);
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Scenario not found: "${name}" (looked for ${filePath})`);
+    }
+    return JSON.parse(raw);
+}
+/**
+ * List all saved scenarios, returning lightweight summary objects.
+ *
+ * Scenarios with unreadable or malformed files are silently skipped.
+ */
+export async function listScenarios() {
+    ensureScenariosDir();
+    let files;
+    try {
+        files = readdirSync(SCENARIOS_DIR);
+    }
+    catch {
+        return [];
+    }
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
+    const summaries = [];
+    for (const file of jsonFiles) {
+        const filePath = join(SCENARIOS_DIR, file);
+        try {
+            const raw = readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            summaries.push({
+                name: data.name,
+                createdAt: data.createdAt,
+                adjustmentType: data.adjustmentType,
+                adjustmentValue: data.adjustmentValue,
+                ...(data.description !== undefined ? { description: data.description } : {}),
+                totalProjected: data.totals.totalProjected,
+                percentageChange: data.totals.percentageChange,
+            });
+        }
+        catch {
+            // Skip unreadable/malformed scenario files
+        }
+    }
+    // Sort newest first
+    summaries.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return summaries;
+}
+/**
+ * Compare two or more scenarios side by side.
+ *
+ * For each program that appears in any of the loaded scenarios, the result
+ * includes the actual unit count and the projected units from each scenario.
+ * Programs missing from a given scenario will have projectedUnits of 0.
+ */
+export async function compareScenarios(names) {
+    if (names.length < 2) {
+        throw new Error('compareScenarios requires at least 2 scenario names');
+    }
+    // Load all scenarios in parallel
+    const loaded = await Promise.all(names.map((n) => loadScenario(n)));
+    // Build a unified map of programCode -> { masterProgram, actual, projectedByScenario }
+    const programMap = new Map();
+    for (const scenario of loaded) {
+        for (const p of scenario.projections) {
+            const existing = programMap.get(p.programCode);
+            if (existing) {
+                existing.projectedByScenario[scenario.name] = p.projectedUnits;
+                // Keep the actual from whichever scenario we see first
+            }
+            else {
+                programMap.set(p.programCode, {
+                    masterProgram: p.masterProgram,
+                    actual: p.actualUnits,
+                    projectedByScenario: { [scenario.name]: p.projectedUnits },
+                });
+            }
+        }
+    }
+    // Fill in zeros for scenarios that don't have a given program
+    for (const entry of programMap.values()) {
+        for (const scenario of loaded) {
+            if (!(scenario.name in entry.projectedByScenario)) {
+                entry.projectedByScenario[scenario.name] = 0;
+            }
+        }
+    }
+    const programs = Array.from(programMap.entries())
+        .map(([programCode, entry]) => ({
+        programCode,
+        masterProgram: entry.masterProgram,
+        actual: entry.actual,
+        projectedByScenario: entry.projectedByScenario,
+    }))
+        .sort((a, b) => a.programCode.localeCompare(b.programCode));
+    const totalsByScenario = {};
+    for (const scenario of loaded) {
+        totalsByScenario[scenario.name] = {
+            totalProjected: scenario.totals.totalProjected,
+            percentageChange: scenario.totals.percentageChange,
+        };
+    }
+    return {
+        scenarioNames: loaded.map((s) => s.name),
+        programs,
+        totalsByScenario,
+    };
+}
+/**
+ * Delete a scenario file from disk.
+ *
+ * Throws if the scenario does not exist.
+ */
+export async function deleteScenario(name) {
+    const sanitized = sanitizeName(name);
+    const filePath = scenarioPath(sanitized);
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        throw new Error(`Scenario not found: "${name}" (looked for ${filePath})`);
+    }
+}

package/dist/lib/cms/publish-blog.d.ts

@@ -0,0 +1,62 @@
+import 'dotenv/config';
+import { StrapiItem } from './strapi-client.js';
+export interface PublishBlogOptions {
+    slug: string;
+    deployAfter?: boolean;
+    site?: string;
+}
+export interface PublishBlogResult {
+    documentId: string;
+    slug: string;
+    published: boolean;
+    deployUrl?: string;
+}
+export interface BlogPostData {
+    title: string;
+    slug: string;
+    content: string;
+    site: string;
+    tags?: string[];
+    excerpt?: string;
+}
+export interface BlogPostSummary {
+    documentId: string;
+    title: string;
+    slug: string;
+    site: string;
+    createdAt: string;
+}
+/**
+ * Main orchestrator: find a blog post by slug, publish it in Strapi,
+ * and optionally deploy the portfolio site to Vercel.
+ *
+ * @throws If no blog post is found for the given slug.
+ *
+ * @example
+ *   const result = await publishBlog({ slug: 'copper-investment-thesis-2026', deployAfter: true })
+ *   console.log(result.deployUrl) // https://portfolio-2026.vercel.app
+ */
+export declare function publishBlog(opts: PublishBlogOptions): Promise<PublishBlogResult>;
+/**
+ * Create a new blog post draft in Strapi.
+ *
+ * @example
+ *   const post = await createBlogPost({
+ *     title: 'Copper Investment Thesis 2026',
+ *     slug: 'copper-investment-thesis-2026',
+ *     content: '## Overview\n...',
+ *     site: 'portfolio',
+ *     tags: ['Automated Report'],
+ *   })
+ */
+export declare function createBlogPost(data: BlogPostData): Promise<StrapiItem>;
+/**
+ * List unpublished blog post drafts from Strapi, optionally filtered by site.
+ *
+ * @param site - Optional site key to filter by (e.g. 'portfolio', 'insurance').
+ *
+ * @example
+ *   const drafts = await listBlogDrafts('portfolio')
+ *   drafts.forEach(d => console.log(d.slug, d.createdAt))
+ */
+export declare function listBlogDrafts(site?: string): Promise<BlogPostSummary[]>;

package/dist/lib/cms/publish-blog.js

@@ -0,0 +1,74 @@
+import 'dotenv/config';
+import { deploy } from '../infra/deploy.js';
+import { strapiGet, strapiPost, findBySlug, publish, } from './strapi-client.js';
+// ── Functions ─────────────────────────────────────────────────────────
+/**
+ * Main orchestrator: find a blog post by slug, publish it in Strapi,
+ * and optionally deploy the portfolio site to Vercel.
+ *
+ * @throws If no blog post is found for the given slug.
+ *
+ * @example
+ *   const result = await publishBlog({ slug: 'copper-investment-thesis-2026', deployAfter: true })
+ *   console.log(result.deployUrl) // https://portfolio-2026.vercel.app
+ */
+export async function publishBlog(opts) {
+    const { slug, deployAfter = false } = opts;
+    const item = await findBySlug('blog-posts', slug);
+    if (!item) {
+        throw new Error(`Blog post not found for slug: "${slug}"`);
+    }
+    const { documentId } = item;
+    await publish('blog-posts', documentId);
+    let deployUrl;
+    if (deployAfter) {
+        deployUrl = await deploy('portfolio', true);
+    }
+    return {
+        documentId,
+        slug,
+        published: true,
+        ...(deployUrl !== undefined ? { deployUrl } : {}),
+    };
+}
+/**
+ * Create a new blog post draft in Strapi.
+ *
+ * @example
+ *   const post = await createBlogPost({
+ *     title: 'Copper Investment Thesis 2026',
+ *     slug: 'copper-investment-thesis-2026',
+ *     content: '## Overview\n...',
+ *     site: 'portfolio',
+ *     tags: ['Automated Report'],
+ *   })
+ */
+export async function createBlogPost(data) {
+    return strapiPost('/api/blog-posts', data);
+}
+/**
+ * List unpublished blog post drafts from Strapi, optionally filtered by site.
+ *
+ * @param site - Optional site key to filter by (e.g. 'portfolio', 'insurance').
+ *
+ * @example
+ *   const drafts = await listBlogDrafts('portfolio')
+ *   drafts.forEach(d => console.log(d.slug, d.createdAt))
+ */
+export async function listBlogDrafts(site) {
+    const params = {
+        status: 'draft',
+        'sort': 'createdAt:desc',
+    };
+    if (site) {
+        params['filters[site][$eq]'] = site;
+    }
+    const result = await strapiGet('/api/blog-posts', params);
+    return result.data.map((item) => ({
+        documentId: item.documentId,
+        title: String(item.title ?? ''),
+        slug: String(item.slug ?? ''),
+        site: String(item.site ?? ''),
+        createdAt: String(item.createdAt ?? ''),
+    }));
+}

package/dist/lib/cms/strapi-client.d.ts

@@ -0,0 +1,123 @@
+import 'dotenv/config';
+export interface StrapiItem {
+    id: number;
+    documentId: string;
+    [key: string]: unknown;
+}
+export interface StrapiPagination {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    total: number;
+}
+export interface StrapiPage {
+    data: StrapiItem[];
+    meta: {
+        pagination: StrapiPagination;
+    };
+}
+export interface StrapiError {
+    status: number;
+    name: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare class StrapiClientError extends Error {
+    status: number;
+    strapiError?: StrapiError | undefined;
+    constructor(message: string, status: number, strapiError?: StrapiError | undefined);
+}
+/**
+ * GET a Strapi endpoint with optional query params.
+ * Returns the full parsed JSON response.
+ *
+ * @example
+ *   const result = await strapiGet('/api/newsletters', { 'status': 'draft' })
+ */
+export declare function strapiGet<T = StrapiPage>(endpoint: string, params?: Record<string, string>): Promise<T>;
+/**
+ * POST to a Strapi endpoint. Wraps data in `{ data }` per Strapi v5 convention.
+ * Returns the created item.
+ *
+ * @example
+ *   const item = await strapiPost('/api/social-posts', {
+ *     headline: 'New post',
+ *     brand: 'LIFEINSUR',
+ *   })
+ */
+export declare function strapiPost(endpoint: string, data: Record<string, unknown>): Promise<StrapiItem>;
+/**
+ * PUT to a Strapi endpoint by documentId. Wraps data in `{ data }`.
+ *
+ * IMPORTANT: Strapi v5 uses documentId (UUID string), NOT numeric id.
+ *
+ * @example
+ *   await strapiPut('/api/newsletters', 'abc123-def456', { subject_line: 'Updated' })
+ */
+export declare function strapiPut(endpoint: string, documentId: string, data: Record<string, unknown>): Promise<StrapiItem>;
+/**
+ * DELETE a Strapi item by documentId.
+ *
+ * IMPORTANT: Strapi v5 uses documentId (UUID string), NOT numeric id.
+ *
+ * @example
+ *   await strapiDelete('/api/social-posts', 'abc123-def456')
+ */
+export declare function strapiDelete(endpoint: string, documentId: string): Promise<void>;
+/**
+ * Upload a file to Strapi's `/api/upload` endpoint via multipart form.
+ *
+ * Optionally link the upload to an existing entry via `refData`:
+ *   - ref: content type UID (e.g. 'api::newsletter.newsletter')
+ *   - refId: documentId of the entry to attach to
+ *   - field: field name on the content type (e.g. 'cover_image')
+ *
+ * @example
+ *   const uploaded = await strapiUploadFile('/path/to/image.png')
+ *   const linked = await strapiUploadFile('/path/to/cover.jpg', {
+ *     ref: 'api::blog-post.blog-post',
+ *     refId: 'abc123',
+ *     field: 'cover',
+ *   })
+ */
+export declare function strapiUploadFile(filePath: string, refData?: {
+    ref: string;
+    refId: string;
+    field: string;
+}): Promise<StrapiItem[]>;
+/**
+ * List items of a content type filtered by brand, with optional status filter.
+ * This is the most common query pattern in Optimal's multi-brand CMS setup.
+ *
+ * Content types: 'newsletters', 'social-posts', 'blog-posts'
+ * Brands: 'CRE-11TRUST', 'LIFEINSUR'
+ * Status: 'draft' or 'published' (Strapi's draftAndPublish)
+ *
+ * @example
+ *   const drafts = await listByBrand('social-posts', 'LIFEINSUR', 'draft')
+ *   const published = await listByBrand('newsletters', 'CRE-11TRUST', 'published')
+ *   const all = await listByBrand('blog-posts', 'CRE-11TRUST')
+ */
+export declare function listByBrand(contentType: string, brand: string, status?: 'draft' | 'published'): Promise<StrapiPage>;
+/**
+ * Find a single item by slug within a content type.
+ * Returns null if not found.
+ *
+ * @example
+ *   const post = await findBySlug('blog-posts', 'copper-investment-thesis-2026')
+ */
+export declare function findBySlug(contentType: string, slug: string): Promise<StrapiItem | null>;
+/**
+ * Publish an item by setting publishedAt via PUT.
+ *
+ * @example
+ *   await publish('newsletters', 'abc123-def456')
+ */
+export declare function publish(contentType: string, documentId: string): Promise<StrapiItem>;
+/**
+ * Unpublish (revert to draft) by clearing publishedAt.
+ *
+ * @example
+ *   await unpublish('newsletters', 'abc123-def456')
+ */
+export declare function unpublish(contentType: string, documentId: string): Promise<StrapiItem>;

package/dist/lib/cms/strapi-client.js

@@ -0,0 +1,213 @@
+import 'dotenv/config';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+export class StrapiClientError extends Error {
+    status;
+    strapiError;
+    constructor(message, status, strapiError) {
+        super(message);
+        this.status = status;
+        this.strapiError = strapiError;
+        this.name = 'StrapiClientError';
+    }
+}
+// ── Config ───────────────────────────────────────────────────────────
+function getConfig() {
+    const url = process.env.STRAPI_URL;
+    const token = process.env.STRAPI_API_TOKEN;
+    if (!url || !token) {
+        throw new Error('Missing env vars: STRAPI_URL, STRAPI_API_TOKEN');
+    }
+    return { url: url.replace(/\/+$/, ''), token };
+}
+// ── Internal request helper ──────────────────────────────────────────
+async function request(path, opts = {}) {
+    const { url, token } = getConfig();
+    const fullUrl = `${url}${path}`;
+    const res = await fetch(fullUrl, {
+        ...opts,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            ...opts.headers,
+        },
+    });
+    if (!res.ok) {
+        let strapiErr;
+        try {
+            const body = await res.json();
+            strapiErr = body?.error;
+        }
+        catch {
+            // non-JSON error body
+        }
+        throw new StrapiClientError(strapiErr?.message ?? `Strapi ${res.status}: ${res.statusText}`, res.status, strapiErr);
+    }
+    if (res.status === 204)
+        return undefined;
+    return res.json();
+}
+// ── CRUD Functions ───────────────────────────────────────────────────
+/**
+ * GET a Strapi endpoint with optional query params.
+ * Returns the full parsed JSON response.
+ *
+ * @example
+ *   const result = await strapiGet('/api/newsletters', { 'status': 'draft' })
+ */
+export async function strapiGet(endpoint, params) {
+    const qs = params ? new URLSearchParams(params).toString() : '';
+    const path = qs ? `${endpoint}?${qs}` : endpoint;
+    return request(path);
+}
+/**
+ * POST to a Strapi endpoint. Wraps data in `{ data }` per Strapi v5 convention.
+ * Returns the created item.
+ *
+ * @example
+ *   const item = await strapiPost('/api/social-posts', {
+ *     headline: 'New post',
+ *     brand: 'LIFEINSUR',
+ *   })
+ */
+export async function strapiPost(endpoint, data) {
+    const result = await request(endpoint, {
+        method: 'POST',
+        body: JSON.stringify({ data }),
+    });
+    return result.data;
+}
+/**
+ * PUT to a Strapi endpoint by documentId. Wraps data in `{ data }`.
+ *
+ * IMPORTANT: Strapi v5 uses documentId (UUID string), NOT numeric id.
+ *
+ * @example
+ *   await strapiPut('/api/newsletters', 'abc123-def456', { subject_line: 'Updated' })
+ */
+export async function strapiPut(endpoint, documentId, data) {
+    const result = await request(`${endpoint}/${documentId}`, {
+        method: 'PUT',
+        body: JSON.stringify({ data }),
+    });
+    return result.data;
+}
+/**
+ * DELETE a Strapi item by documentId.
+ *
+ * IMPORTANT: Strapi v5 uses documentId (UUID string), NOT numeric id.
+ *
+ * @example
+ *   await strapiDelete('/api/social-posts', 'abc123-def456')
+ */
+export async function strapiDelete(endpoint, documentId) {
+    await request(`${endpoint}/${documentId}`, { method: 'DELETE' });
+}
+/**
+ * Upload a file to Strapi's `/api/upload` endpoint via multipart form.
+ *
+ * Optionally link the upload to an existing entry via `refData`:
+ *   - ref: content type UID (e.g. 'api::newsletter.newsletter')
+ *   - refId: documentId of the entry to attach to
+ *   - field: field name on the content type (e.g. 'cover_image')
+ *
+ * @example
+ *   const uploaded = await strapiUploadFile('/path/to/image.png')
+ *   const linked = await strapiUploadFile('/path/to/cover.jpg', {
+ *     ref: 'api::blog-post.blog-post',
+ *     refId: 'abc123',
+ *     field: 'cover',
+ *   })
+ */
+export async function strapiUploadFile(filePath, refData) {
+    const { url, token } = getConfig();
+    const fileBuffer = readFileSync(filePath);
+    const fileName = basename(filePath);
+    const formData = new FormData();
+    formData.append('files', new Blob([fileBuffer]), fileName);
+    if (refData) {
+        formData.append('ref', refData.ref);
+        formData.append('refId', refData.refId);
+        formData.append('field', refData.field);
+    }
+    const res = await fetch(`${url}/api/upload`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            // Do NOT set Content-Type — fetch sets it with the multipart boundary
+        },
+        body: formData,
+    });
+    if (!res.ok) {
+        let strapiErr;
+        try {
+            const body = await res.json();
+            strapiErr = body?.error;
+        }
+        catch {
+            // non-JSON error body
+        }
+        throw new StrapiClientError(strapiErr?.message ?? `Upload failed ${res.status}: ${res.statusText}`, res.status, strapiErr);
+    }
+    return res.json();
+}
+// ── Convenience ──────────────────────────────────────────────────────
+/**
+ * List items of a content type filtered by brand, with optional status filter.
+ * This is the most common query pattern in Optimal's multi-brand CMS setup.
+ *
+ * Content types: 'newsletters', 'social-posts', 'blog-posts'
+ * Brands: 'CRE-11TRUST', 'LIFEINSUR'
+ * Status: 'draft' or 'published' (Strapi's draftAndPublish)
+ *
+ * @example
+ *   const drafts = await listByBrand('social-posts', 'LIFEINSUR', 'draft')
+ *   const published = await listByBrand('newsletters', 'CRE-11TRUST', 'published')
+ *   const all = await listByBrand('blog-posts', 'CRE-11TRUST')
+ */
+export async function listByBrand(contentType, brand, status) {
+    const params = {
+        'filters[brand][$eq]': brand,
+        'sort': 'createdAt:desc',
+    };
+    if (status) {
+        params['status'] = status;
+    }
+    return strapiGet(`/api/${contentType}`, params);
+}
+/**
+ * Find a single item by slug within a content type.
+ * Returns null if not found.
+ *
+ * @example
+ *   const post = await findBySlug('blog-posts', 'copper-investment-thesis-2026')
+ */
+export async function findBySlug(contentType, slug) {
+    const result = await strapiGet(`/api/${contentType}`, {
+        'filters[slug][$eq]': slug,
+        'pagination[pageSize]': '1',
+    });
+    return result.data[0] ?? null;
+}
+/**
+ * Publish an item by setting publishedAt via PUT.
+ *
+ * @example
+ *   await publish('newsletters', 'abc123-def456')
+ */
+export async function publish(contentType, documentId) {
+    return strapiPut(`/api/${contentType}`, documentId, {
+        publishedAt: new Date().toISOString(),
+    });
+}
+/**
+ * Unpublish (revert to draft) by clearing publishedAt.
+ *
+ * @example
+ *   await unpublish('newsletters', 'abc123-def456')
+ */
+export async function unpublish(contentType, documentId) {
+    return strapiPut(`/api/${contentType}`, documentId, {
+        publishedAt: null,
+    });
+}