clearhand 0.1.0

package/dist/server/demo.js

@@ -0,0 +1,194 @@
+import { now } from './db/index.js';
+/**
+ * Demo mode: seeded sample cases + simulated connectors so anyone can run
+ * `clearhand demo`, click through the full propose → approve → execute loop,
+ * and watch every guard fire — without connecting a real Stripe account or
+ * mailbox. No external host is contacted in demo mode.
+ */
+export function makeDemoExecutorOps() {
+    // Simulated Stripe state, keyed by id. sub_demo2 is already scheduled to
+    // cancel — approving another end_of_period cancel demonstrates the
+    // proration guard's idempotent no-op.
+    const subs = new Map([
+        ['sub_demoAAAAAAAAAAAA', { id: 'sub_demoAAAAAAAAAAAA', status: 'active', cancel_at_period_end: false, cancel_at: null }],
+        ['sub_demoBBBBBBBBBBBB', { id: 'sub_demoBBBBBBBBBBBB', status: 'active', cancel_at_period_end: true, cancel_at: null }],
+    ]);
+    const charges = new Map([
+        ['ch_demoAAAAAAAAAAAAA', { id: 'ch_demoAAAAAAAAAAAAA', amount: 2900, currency: 'usd', refunded: false, amount_refunded: 0 }],
+        ['ch_demoBBBBBBBBBBBBB', { id: 'ch_demoBBBBBBBBBBBBB', amount: 9900, currency: 'usd', refunded: false, amount_refunded: 0 }],
+    ]);
+    let refundSeq = 0;
+    let issueSeq = 41;
+    return {
+        stripe: {
+            async retrieveSubscription(subId) {
+                const s = subs.get(subId);
+                if (!s)
+                    throw new Error(`resource_missing: No such subscription: ${subId}`);
+                return { ...s };
+            },
+            async cancelNow(subId) {
+                const s = subs.get(subId);
+                if (!s)
+                    throw new Error(`resource_missing: No such subscription: ${subId}`);
+                s.status = 'canceled';
+                return { ...s };
+            },
+            async cancelAtPeriodEnd(subId) {
+                const s = subs.get(subId);
+                if (!s)
+                    throw new Error(`resource_missing: No such subscription: ${subId}`);
+                s.cancel_at_period_end = true;
+                return { ...s };
+            },
+            async cancelAt(subId, epochSeconds) {
+                const s = subs.get(subId);
+                if (!s)
+                    throw new Error(`resource_missing: No such subscription: ${subId}`);
+                s.cancel_at = epochSeconds;
+                return { ...s };
+            },
+            async retrieveCharge(chargeId) {
+                const c = charges.get(chargeId);
+                if (!c)
+                    throw new Error(`resource_missing: No such charge: ${chargeId}`);
+                return { ...c };
+            },
+            async createRefund(params) {
+                const c = charges.get(params.chargeId);
+                if (!c)
+                    throw new Error(`resource_missing: No such charge: ${params.chargeId}`);
+                if (c.refunded)
+                    throw new Error('charge_already_refunded: This charge has already been refunded.');
+                const amount = params.amountCents ?? c.amount;
+                c.amount_refunded += amount;
+                c.refunded = c.amount_refunded >= c.amount;
+                return { id: `re_demo${++refundSeq}`, status: 'succeeded', amount };
+            },
+            async latestPaidInvoiceCharge(subId) {
+                return subId === 'sub_demoAAAAAAAAAAAA' ? 'ch_demoAAAAAAAAAAAAA' : null;
+            },
+        },
+        mailer: {
+            async sendReply(params) {
+                return { providerMessageId: `<demo-${Date.now()}@clearhand.local>` };
+            },
+        },
+        github: {
+            async createIssue(params) {
+                return { number: ++issueSeq, url: `https://github.com/demo/app/issues/${issueSeq}` };
+            },
+        },
+    };
+}
+export function seedDemoData(db) {
+    if (db.prepare(`SELECT COUNT(*) AS n FROM cases`).get().n > 0)
+        return;
+    const t = now();
+    const customer = (email, name) => Number(db
+        .prepare(`INSERT INTO customers (email, name, created_at, updated_at) VALUES (?, ?, ?, ?)`)
+        .run(email, name, t, t).lastInsertRowid);
+    const mkCase = (customerId, subject, category, summary, ctx) => Number(db
+        .prepare(`INSERT INTO cases (customer_id, source, conversation_key, subject, status, category, summary,
+                              prepared_context_json, enriched_at, created_at, updated_at)
+           VALUES (?, 'demo', ?, ?, 'processed', ?, ?, ?, ?, ?, ?)`)
+        .run(customerId, `demo-${subject}`, subject, category, summary, JSON.stringify(ctx), t, t, t).lastInsertRowid);
+    const email = (caseId, from, subject, body) => db
+        .prepare(`INSERT INTO emails (case_id, direction, from_addr, to_addr, subject, body_text, provider_message_id, received_at, created_at)
+         VALUES (?, 'inbound', ?, 'support@demo.app', ?, ?, ?, ?, ?)`)
+        .run(caseId, from, subject, body, `<demo-${caseId}-${Math.abs(subject.length)}@mail.example>`, t, t);
+    const draft = (caseId, body) => db
+        .prepare(`INSERT INTO drafts (case_id, version, body_english, is_current, created_by, created_at)
+         VALUES (?, 1, ?, 1, 'agent', ?)`)
+        .run(caseId, body, t);
+    const action = (caseId, type, proposal, order, confidence) => db
+        .prepare(`INSERT INTO actions (case_id, action_type, status, execution_order, proposal_json, confidence, created_at)
+         VALUES (?, ?, 'proposed', ?, ?, ?, ?)`)
+        .run(caseId, type, order, JSON.stringify(proposal), confidence, t);
+    // Case 1 — refund request, full loop: refund + reply + resolve.
+    const c1cust = customer('mara@example.com', 'Mara Jensen');
+    const stripeCtx1 = {
+        stripe: {
+            found: true,
+            fetchedAt: t,
+            customers: [
+                {
+                    customerId: 'cus_demoAAAAAAAAAAAA',
+                    created: t,
+                    currency: 'usd',
+                    ltvCents: 8700,
+                    subscriptions: [
+                        {
+                            id: 'sub_demoAAAAAAAAAAAA', status: 'active', priceNickname: 'Pro Monthly',
+                            priceId: 'price_demoA', amountCents: 2900, interval: 'month',
+                            currentPeriodEnd: new Date(Date.now() + 12 * 86_400_000).toISOString(),
+                            cancelAtPeriodEnd: false,
+                        },
+                    ],
+                    recentCharges: [
+                        { id: 'ch_demoAAAAAAAAAAAAA', amountCents: 2900, currency: 'usd', created: t, status: 'succeeded', refunded: false, amountRefundedCents: 0 },
+                    ],
+                    refunds: { count: 0, totalCents: 0 },
+                },
+            ],
+        },
+    };
+    const c1 = mkCase(c1cust, 'Please refund my last charge', 'refund', 'Customer was charged after intending to cancel. First refund request; LTV $87; within policy window.', stripeCtx1);
+    email(c1, 'mara@example.com', 'Please refund my last charge', 'Hi, I meant to cancel before renewal but got charged $29 yesterday. Could you refund it and cancel my subscription? Thanks, Mara');
+    draft(c1, 'Hi Mara,\n\nThanks for reaching out. I\'ve refunded the $29.00 charge from yesterday — it should appear on your statement within 5–10 business days. Your subscription is set to cancel at the end of the current period, so you\'ll keep access until then and won\'t be billed again.\n\nDemo Support');
+    action(c1, 'refund', { charge_id: 'ch_demoAAAAAAAAAAAAA', amount_cents: 2900, currency: 'usd', reason: 'Charged after intended cancellation; first refund, within window.' }, 0, 0.93);
+    action(c1, 'cancel_subscription', { subscription_id: 'sub_demoAAAAAAAAAAAA', cancel_mode: 'end_of_period', customer_id: 'cus_demoAAAAAAAAAAAA', reason: 'Customer asked to cancel.' }, 5, 0.95);
+    action(c1, 'send_reply', { body_text: 'Hi Mara,\n\nThanks for reaching out. I\'ve refunded the $29.00 charge from yesterday — it should appear on your statement within 5–10 business days. Your subscription is set to cancel at the end of the current period.\n\nDemo Support', message: 'Confirm refund + end-of-period cancel' }, 10, 0.9);
+    action(c1, 'set_case_status', { target_status: 'resolved', reason: 'Refund + cancel + confirmation cover the request.' }, 99, 0.9);
+    // Case 2 — proration-guard showcase: sub already scheduled to cancel.
+    const c2cust = customer('theo@example.io', 'Theo Brandt');
+    const c2 = mkCase(c2cust, 'Did my cancellation go through?', 'subscription', 'Customer cancelled last week (already scheduled at period end) but got a reminder email and is worried.', {
+        stripe: {
+            found: true, fetchedAt: t,
+            customers: [{
+                    customerId: 'cus_demoBBBBBBBBBBBB', created: t, currency: 'usd', ltvCents: 29700,
+                    subscriptions: [{ id: 'sub_demoBBBBBBBBBBBB', status: 'active', priceNickname: 'Team Annual', priceId: 'price_demoB', amountCents: 9900, interval: 'year', currentPeriodEnd: new Date(Date.now() + 40 * 86_400_000).toISOString(), cancelAtPeriodEnd: true }],
+                    recentCharges: [{ id: 'ch_demoBBBBBBBBBBBBB', amountCents: 9900, currency: 'usd', created: t, status: 'succeeded', refunded: false, amountRefundedCents: 0 }],
+                    refunds: { count: 0, totalCents: 0 },
+                }],
+        },
+    });
+    email(c2, 'theo@example.io', 'Did my cancellation go through?', 'I cancelled my plan last week but just got a "your renewal is coming" email. Is my cancellation actually scheduled? I do NOT want to be charged again.');
+    draft(c2, 'Hi Theo,\n\nThanks for reaching out — I checked, and your cancellation is scheduled correctly: your Team Annual plan will end at the close of the current period and you will not be charged again. The renewal reminder was sent automatically before the cancellation took effect; you can safely ignore it.\n\nDemo Support');
+    // Approving this cancel demonstrates the proration guard: already scheduled
+    // → idempotent no-op, nothing re-applied.
+    action(c2, 'cancel_subscription', { subscription_id: 'sub_demoBBBBBBBBBBBB', cancel_mode: 'end_of_period', customer_id: 'cus_demoBBBBBBBBBBBB', reason: 'Reassure: verify schedule (already scheduled — guard will no-op).' }, 5, 0.88);
+    action(c2, 'send_reply', { body_text: 'Hi Theo,\n\nThanks for reaching out — I checked, and your cancellation is scheduled correctly: your plan ends at the close of the current period and you will not be charged again.\n\nDemo Support', message: 'Reassure cancellation is scheduled' }, 10, 0.92);
+    action(c2, 'set_case_status', { target_status: 'resolved', reason: 'Verified schedule + reassured customer.' }, 99, 0.9);
+    // Case 3 — bug report → GitHub issue + reply.
+    const c3cust = customer('lin@example.dev', 'Lin Okafor');
+    const c3 = mkCase(c3cust, 'Export button broken on Safari', 'bug', 'Reproducible export failure on Safari 17; no billing impact; needs an issue + acknowledgement.', { notes: 'Repro confirmed from screenshot: TypeError in export.js on Safari 17.4.' });
+    email(c3, 'lin@example.dev', 'Export button broken on Safari', 'The CSV export button does nothing on Safari 17.4 (works in Chrome). Console shows "TypeError: undefined is not a function". Screenshot attached.');
+    draft(c3, 'Hi Lin,\n\nThanks for the detailed report — the console error and Safari version made this easy to track. I\'ve filed it with engineering and we\'ll follow up as soon as a fix ships. In the meantime, export works in Chrome and Firefox.\n\nDemo Support');
+    action(c3, 'create_github_issue', { title: 'CSV export button no-ops on Safari 17.4 (TypeError in export.js)', body: 'Reported by a customer (case #3).\n\nRepro: Safari 17.4 → dashboard → Export CSV → nothing happens.\nConsole: `TypeError: undefined is not a function` in export.js.\nWorks in Chrome/Firefox.\n\nCustomer impact: blocked exports for Safari users.', labels: ['bug', 'from-support'] }, 50, 0.9);
+    action(c3, 'send_reply', { body_text: 'Hi Lin,\n\nThanks for the detailed report — the console error and Safari version made this easy to track. I\'ve filed it with engineering and we\'ll follow up as soon as a fix ships. In the meantime, export works in Chrome and Firefox.\n\nDemo Support', message: 'Acknowledge bug + filed issue' }, 10, 0.9);
+    action(c3, 'set_case_status', { target_status: 'pending', reason: 'Waiting on engineering fix before final confirmation.' }, 99, 0.85);
+    // Case 4 — resolve-guard showcase: a resolve proposed while a refund is
+    // still pending. Approving ONLY the status action trips the guard.
+    const c4cust = customer('sofia@example.org', 'Sofia Reyes');
+    const c4 = mkCase(c4cust, 'Double charged this month', 'billing', 'Two charges of $99 this month; one is a duplicate and owed back. GUARD DEMO: try approving only the "resolve" action.', {
+        stripe: {
+            found: true, fetchedAt: t,
+            customers: [{
+                    customerId: 'cus_demoCCCCCCCCCCCC', created: t, currency: 'usd', ltvCents: 19800,
+                    subscriptions: [],
+                    recentCharges: [{ id: 'ch_demoBBBBBBBBBBBBB', amountCents: 9900, currency: 'usd', created: t, status: 'succeeded', refunded: false, amountRefundedCents: 0 }],
+                    refunds: { count: 0, totalCents: 0 },
+                }],
+        },
+    });
+    email(c4, 'sofia@example.org', 'Double charged this month', 'You charged me twice this month — $99 on the 1st and again on the 3rd. Please refund the duplicate.');
+    draft(c4, 'Hi Sofia,\n\nYou\'re right, and I\'m sorry about that — the second $99 charge was a duplicate. I\'ve refunded it in full; it should reach your account within 5–10 business days.\n\nDemo Support');
+    action(c4, 'refund', { charge_id: 'ch_demoBBBBBBBBBBBBB', amount_cents: 9900, currency: 'usd', reason: 'Duplicate charge — full refund owed.' }, 0, 0.97);
+    action(c4, 'set_case_status', { target_status: 'resolved', reason: 'Duplicate refunded.' }, 99, 0.9);
+    // A couple of learning-loop artifacts so the dashboard isn't empty.
+    db.prepare(`INSERT INTO feedback_events (case_id, event_type, original_json, modified_json, diff_summary, created_at)
+     VALUES (?, 'draft_edit', ?, ?, ?, ?)`).run(c1, JSON.stringify({ body: 'Dear Mara, Thank you for contacting us...' }), JSON.stringify({ body: 'Hi Mara, Thanks for reaching out...' }), 'greeting: "Dear" → "Hi"; opener: "Thank you for contacting us" → "Thanks for reaching out"', t);
+    db.prepare(`INSERT INTO calibrations (customer_message, context_note, clearhand_draft, actual_reply, created_at)
+     VALUES (?, ?, ?, ?, ?)`).run('Do you offer a student discount? I\'m doing my thesis and $29/mo is steep.', 'Pricing question; no discount policy in overlay yet.', 'Hi — thanks for asking! We don\'t have a formal student discount today, but if you write in from your university address I can apply 30% off for 6 months while you finish your thesis.\n\nDemo Support', 'Hey! We don\'t have student pricing officially but I\'ll give you 50% for the semester — send me your uni email. Good luck with the thesis!', t);
+}

package/dist/server/index.js

@@ -0,0 +1,51 @@
+import express from 'express';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createAppContext } from './context.js';
+import { apiRouter } from './routes/api.js';
+import { redactionMiddleware } from './secrets/redaction.js';
+/**
+ * The ClearHand local server. Binds to 127.0.0.1 ONLY — the dashboard and API
+ * are never exposed to the network. All JSON/text responses pass through the
+ * redaction middleware before leaving the process.
+ */
+export async function startServer(opts = {}) {
+    const ctx = await createAppContext();
+    const port = opts.port ?? Number(process.env.CLEARHAND_PORT ?? ctx.config.port);
+    const app = express();
+    app.use(express.json({ limit: '2mb' }));
+    app.use(redactionMiddleware(ctx.secrets));
+    app.use('/api', apiRouter(ctx));
+    // Dashboard static assets (built by `npm run build:dashboard` into public/).
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, '../../public'), // dist/server → public
+        path.resolve(here, '../../../public'), // src/server via tsx → public
+    ];
+    const publicDir = candidates.find((p) => fs.existsSync(path.join(p, 'index.html')));
+    if (publicDir) {
+        app.use(express.static(publicDir));
+        // SPA fallback for client-side routes.
+        app.get(/^\/(?!api\/).*/, (_req, res) => res.sendFile(path.join(publicDir, 'index.html')));
+    }
+    else {
+        app.get('/', (_req, res) => res
+            .status(200)
+            .send('ClearHand server is running. Dashboard assets not built yet — run `npm run build:dashboard`.'));
+    }
+    return await new Promise((resolve) => {
+        const server = app.listen(port, '127.0.0.1', () => {
+            console.log(`[clearhand] server on http://localhost:${port}${ctx.demo ? '  (DEMO MODE)' : ''}`);
+            console.log(`[clearhand] secrets backend: ${ctx.secrets.backendName}`);
+            resolve({ port, close: () => server.close() });
+        });
+    });
+}
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) {
+    startServer().catch((err) => {
+        console.error('[clearhand] failed to start:', err);
+        process.exit(1);
+    });
+}