@velaro/cli 1.2.0 → 1.4.8

package/lib/commands/conversation-efficiency.js

@@ -0,0 +1,178 @@
+import { messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro conversation-efficiency ---------------------------------------------
+// CLI surface for the Conversation Efficiency Analysis (Fragmentation Index)
+// report. Endpoints live in velaro-messaging at /Reports/conversation-efficiency/*
+// and apply the caller's siteId from JWT/MCP-key context -- never from CLI args.
+// Gated by the EnableConversationEfficiencyReport entitlement (Professional/
+// Enterprise only); the server returns 403 when the account isn't entitled.
+//
+// Narrative regeneration is intentionally NOT exposed here -- it's rate-limited
+// (max 6/month/site) and stays a deliberate action in the admin UI, not
+// something scriptable on a loop.
+
+function fmtIndex(val) {
+  return val == null ? '-' : Number(val).toFixed(2);
+}
+
+function fmtPct(val) {
+  return val == null ? '-' : `${Number(val).toFixed(1)}%`;
+}
+
+function section(title) {
+  console.log(`\n\x1b[1m-- ${title} ${'-'.repeat(Math.max(0, 55 - title.length))}\x1b[0m`);
+}
+
+const overviewCommand = {
+  command:  'overview',
+  describe: "This week's Fragmentation Index overview (agent vs bot, week-over-week change)",
+  handler:  runCommand(async () => {
+    const data = await messagingGet('/Reports/conversation-efficiency/overview');
+    section('Conversation Efficiency - Overview');
+    console.log(`  Week starting: ${data?.weekStart ?? '-'}`);
+    const rows = data?.rows ?? [];
+    if (!rows.length) { console.log('  No data for the current week yet.'); return; }
+
+    const COL = [12, 10, 10, 14, 16, 10, 10];
+    const header = ['Party', 'Msgs', 'Turns', 'Convs', 'Frag. Index', 'WoW %', 'Outlier'];
+    console.log('\n  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+    console.log('  ' + '-'.repeat(COL.reduce((a, b) => a + b, 0)));
+    for (const r of rows) {
+      const row = [
+        String(r.partyType ?? '-'),
+        String(r.messageCount ?? '-'),
+        String(r.turnCount ?? '-'),
+        String(r.conversationCount ?? '-'),
+        fmtIndex(r.avgFragmentationIndex),
+        fmtPct(r.weekOverWeekDeltaPct),
+        r.isOutlier ? 'yes' : 'no',
+      ];
+      console.log('  ' + row.map((v, i) => v.padEnd(COL[i])).join(''));
+    }
+    console.log('');
+  }),
+};
+
+const agentsCommand = {
+  command:  'agents',
+  describe: "This week's per-agent Fragmentation Index breakdown",
+  handler:  runCommand(async () => {
+    const data = await messagingGet('/Reports/conversation-efficiency/agents');
+    section('Conversation Efficiency - Agents');
+    console.log(`  Week starting: ${data?.weekStart ?? '-'}`);
+    const rows = data?.rows ?? [];
+    if (!rows.length) { console.log('  No per-agent data for the current week yet.'); return; }
+
+    const COL = [12, 10, 10, 14, 16, 10];
+    const header = ['Agent ID', 'Msgs', 'Turns', 'Convs', 'Frag. Index', 'Outlier'];
+    console.log('\n  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+    console.log('  ' + '-'.repeat(COL.reduce((a, b) => a + b, 0)));
+    for (const r of rows) {
+      const row = [
+        String(r.agentId ?? '-'),
+        String(r.messageCount ?? '-'),
+        String(r.turnCount ?? '-'),
+        String(r.conversationCount ?? '-'),
+        fmtIndex(r.avgFragmentationIndex),
+        r.isOutlier ? 'yes' : 'no',
+      ];
+      console.log('  ' + row.map((v, i) => v.padEnd(COL[i])).join(''));
+    }
+    console.log('');
+  }),
+};
+
+const trendsCommand = {
+  command:  'trends',
+  describe: 'Fragmentation Index trend line over a rolling window of weeks',
+  builder:  (y) => y
+    .option('weeks', { type: 'number', default: 12, describe: 'Number of trailing weeks to include, 1-52 (default 12)' }),
+  handler:  runCommand(async (argv) => {
+    const qs = new URLSearchParams();
+    if (argv.weeks) qs.set('weeks', String(argv.weeks));
+    const rows = await messagingGet(`/Reports/conversation-efficiency/trends?${qs.toString()}`);
+    section('Conversation Efficiency - Trends');
+    if (!Array.isArray(rows) || !rows.length) { console.log('  No trend data yet.'); return; }
+
+    const COL = [14, 12, 10, 14, 10, 10];
+    const header = ['Week', 'Party', 'Agent', 'Frag. Index', 'Convs', 'Outlier'];
+    console.log('\n  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+    console.log('  ' + '-'.repeat(COL.reduce((a, b) => a + b, 0)));
+    for (const r of rows) {
+      const row = [
+        String(r.snapshotWeek ?? '-').slice(0, 12),
+        String(r.partyType ?? '-'),
+        String(r.agentId ?? 'site'),
+        fmtIndex(r.avgFragmentationIndex),
+        String(r.conversationCount ?? '-'),
+        r.isOutlier ? 'yes' : 'no',
+      ];
+      console.log('  ' + row.map((v, i) => v.padEnd(COL[i])).join(''));
+    }
+    console.log('');
+  }),
+};
+
+const correlationCommand = {
+  command:  'correlation',
+  describe: 'Correlation between Fragmentation Index and survey rating (last 8 weeks)',
+  handler:  runCommand(async () => {
+    const data = await messagingGet('/Reports/conversation-efficiency/correlation');
+    section('Conversation Efficiency - Correlation');
+    console.log(`  Sample size: ${data?.sampleSize ?? 0}`);
+    console.log(`  ${data?.description ?? 'Not enough data yet.'}`);
+    console.log('');
+  }),
+};
+
+const narrativeCommand = {
+  command:  'narrative',
+  describe: 'Most recent AI-generated narrative summary (read-only -- does not regenerate)',
+  handler:  runCommand(async () => {
+    const data = await messagingGet('/Reports/conversation-efficiency/narrative');
+    section('Conversation Efficiency - Narrative');
+    if (!data?.narrative) { console.log('  No narrative generated yet.'); return; }
+    console.log(`  Period: ${data.periodStart ?? '-'} -> ${data.periodEnd ?? '-'}`);
+    console.log(`  Generated: ${data.generatedAt ?? '-'}`);
+    console.log(`\n  ${data.narrative}\n`);
+  }),
+};
+
+// Recommendations list is read-only here on purpose -- apply/rollback change a bot's live
+// prompt configuration and stay a human-driven admin UI action, same judgment call as
+// narrative regeneration above. There is no `conversation-efficiency recommendations apply`
+// or `... rollback` subcommand.
+const recommendationsCommand = {
+  command:  'recommendations',
+  describe: 'List closed-loop corrective recommendations for this site\'s bots (read-only)',
+  handler:  runCommand(async () => {
+    const recs = await messagingGet('/Reports/conversation-efficiency/recommendations');
+    section('Conversation Efficiency - Recommendations');
+    if (!Array.isArray(recs) || !recs.length) { console.log('  No recommendations right now.'); return; }
+
+    for (const r of recs) {
+      const status = r.rolledBackAt ? 'rolled back' : r.appliedAt ? 'applied' : 'pending review';
+      console.log(`\n  #${r.id} [${status}] -- ${r.title}`);
+      console.log(`  Week: ${r.snapshotWeek ?? '-'}  Frag. Index: ${fmtIndex(r.sourceFragmentationIndex)}  Conversion gap: ${fmtPct(r.sourceConversionDelta)}`);
+      console.log(`  ${r.body ?? ''}`);
+      if (r.appliedAt) console.log(`  Applied ${r.appliedAt} by ${r.appliedBy ?? 'unknown'}`);
+      if (r.rolledBackAt) console.log(`  Rolled back ${r.rolledBackAt} by ${r.rolledBackBy ?? 'unknown'}${r.rollbackNotes ? ` -- "${r.rollbackNotes}"` : ''}`);
+    }
+    console.log('\n  Apply/rollback are admin-UI-only actions -- not available via this CLI.\n');
+  }),
+};
+
+export const conversationEfficiencyCommand = {
+  command:  'conversation-efficiency',
+  describe: 'Conversation Efficiency Analysis (Fragmentation Index) -- Professional/Enterprise',
+  builder:  (y) => y
+    .command(overviewCommand)
+    .command(agentsCommand)
+    .command(trendsCommand)
+    .command(correlationCommand)
+    .command(narrativeCommand)
+    .command(recommendationsCommand)
+    .demandCommand(1, 'Specify a subcommand. Run "velaro conversation-efficiency --help" for options.'),
+  handler: () => {},
+};

package/lib/commands/copilotstudio.js

@@ -0,0 +1,114 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro copilotstudio -----------------------------------------------------
+// Manage connections to Microsoft Copilot Studio agents and Azure AI Foundry
+// agents for the logged-in site - live external knowledge sources the bot
+// forwards questions to in real time (not ingested).
+//
+// Backend contract: server/Velaro.Admin/Controllers/CopilotStudioController.cs
+// Site is resolved server-side from the auth context - never caller-supplied.
+
+function printConfig(c) {
+  console.log(`  [${c.id}] ${c.name}  type=${c.agentType}  ${c.isActive ? 'enabled' : 'DISABLED'}`);
+  console.log(`       routing: ${c.whenToUseDescription ? `"${c.whenToUseDescription}"` : '(none set)'}`);
+}
+
+export const copilotStudioCommand = {
+  command:  'copilotstudio <subcommand>',
+  describe: 'Manage Microsoft Copilot Studio / Azure AI Foundry agent connections for this site',
+  builder:  yargs => yargs
+    .command({
+      command:  'list',
+      describe: 'List connected Copilot Studio / Azure AI Foundry agents',
+      handler:  runCommand(async () => {
+        const configs = await request('GET', '/CopilotStudio/configs');
+        if (!Array.isArray(configs) || !configs.length) {
+          console.log('\nNo connected Copilot Studio or Azure AI agents configured for this site.');
+          console.log('Use "velaro copilotstudio add" to connect one.\n');
+          return;
+        }
+        console.log(`\n=== Connected Agents (${configs.length}) ===`);
+        for (const c of configs) printConfig(c);
+        console.log('');
+      }),
+    })
+    .command({
+      command:  'add',
+      describe: 'Connect a new Copilot Studio (Direct Line) or Azure AI Foundry agent',
+      builder:  y => y
+        .option('name',                    { type: 'string',  demandOption: true,  describe: 'Display name for this agent connection' })
+        .option('agent-type',              { type: 'string',  demandOption: true,  choices: ['copilot-studio', 'azure-ai-agent'], describe: 'copilot-studio = Direct Line; azure-ai-agent = Azure AI Foundry REST' })
+        .option('when-to-use',             { type: 'string',  demandOption: true,  describe: 'Plain-language description of what questions this agent answers' })
+        .option('direct-line-secret',      { type: 'string',  demandOption: false, describe: 'Direct Line secret (copilot-studio only)' })
+        .option('azure-endpoint',          { type: 'string',  demandOption: false, describe: 'Azure AI Foundry endpoint URL (azure-ai-agent only)' })
+        .option('azure-agent-id',          { type: 'string',  demandOption: false, describe: 'Azure AI Foundry agent ID (azure-ai-agent only)' })
+        .option('azure-api-key',           { type: 'string',  demandOption: false, describe: 'Azure AI Foundry API key (azure-ai-agent only)' }),
+      handler:  runCommand(async argv => {
+        if (argv['agent-type'] === 'copilot-studio' && !argv['direct-line-secret']) {
+          throw new Error('--direct-line-secret is required for agent-type copilot-studio');
+        }
+        if (argv['agent-type'] === 'azure-ai-agent' && (!argv['azure-endpoint'] || !argv['azure-agent-id'] || !argv['azure-api-key'])) {
+          throw new Error('--azure-endpoint, --azure-agent-id, and --azure-api-key are all required for agent-type azure-ai-agent');
+        }
+        const created = await request('POST', '/CopilotStudio/configs', {
+          name:                 argv.name,
+          agentType:            argv['agent-type'],
+          whenToUseDescription: argv['when-to-use'],
+          directLineSecret:     argv['direct-line-secret'] || null,
+          azureEndpoint:        argv['azure-endpoint'] || null,
+          azureAgentId:         argv['azure-agent-id'] || null,
+          azureApiKey:          argv['azure-api-key'] || null,
+        });
+        console.log(`\nConnected agent "${created.name}" added (id=${created.id})\n`);
+        printConfig(created);
+        console.log('');
+      }),
+    })
+    .command({
+      command:  'update <id>',
+      describe: 'Update name, enabled status, or routing description of an existing connection',
+      builder:  y => y
+        .positional('id',    { type: 'number', describe: 'Config ID from "velaro copilotstudio list"' })
+        .option('name',      { type: 'string',  demandOption: false, describe: 'New display name' })
+        .option('enable',    { type: 'boolean', demandOption: false, describe: 'Enable the agent' })
+        .option('disable',   { type: 'boolean', demandOption: false, describe: 'Disable the agent' })
+        .option('when-to-use', { type: 'string', demandOption: false, describe: 'New routing description (pass "" to clear)' }),
+      handler:  runCommand(async argv => {
+        if (argv.enable && argv.disable) throw new Error('Pass only one of --enable or --disable, not both.');
+        const payload = {
+          name:                 argv.name ?? null,
+          isActive:             argv.enable ? true : argv.disable ? false : null,
+          whenToUseDescription: argv['when-to-use'] ?? null,
+        };
+        const updated = await request('PUT', `/CopilotStudio/configs/${argv.id}`, payload);
+        console.log(`\nAgent connection ${argv.id} updated\n`);
+        printConfig(updated);
+        console.log('');
+      }),
+    })
+    .command({
+      command:  'remove <id>',
+      describe: 'Remove a connected agent',
+      builder:  y => y.positional('id', { type: 'number', describe: 'Config ID from "velaro copilotstudio list"' }),
+      handler:  runCommand(async argv => {
+        await request('DELETE', `/CopilotStudio/configs/${argv.id}`);
+        console.log(`\nAgent connection ${argv.id} removed\n`);
+      }),
+    })
+    .command({
+      command:  'test <id>',
+      describe: 'Test connectivity for an agent (Direct Line ping / Azure AI Foundry assistant fetch)',
+      builder:  y => y.positional('id', { type: 'number', describe: 'Config ID from "velaro copilotstudio list"' }),
+      handler:  runCommand(async argv => {
+        const result = await request('POST', `/CopilotStudio/configs/${argv.id}/test`);
+        if (result?.success) {
+          console.log(`\nConnection test succeeded for agent ${argv.id}\n`);
+        } else {
+          console.log(`\nConnection test FAILED for agent ${argv.id}: ${result?.error ?? 'unknown error'}\n`);
+          process.exitCode = 1;
+        }
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: list | add | update | remove | test'),
+};

package/lib/commands/coupon-grant.js

@@ -0,0 +1,192 @@
+// CLI surface for per-account Stripe discount grants (velaro-admin
+// BillingCouponGrantController). Velaro-billing-staff only, same as the REST endpoints — the API
+// enforces the role gate, this is just a convenient front end for it.
+//
+// NOTE ON SCOPE: this manages Velaro's STRIPE-side discount grants. The reusable coupon-CODE
+// catalog is a separate, pre-existing system in velaro-messaging
+// (superadmin/billing/coupons + BillingCoupons table); use `--coupon-code` here to record which
+// catalog code a grant corresponds to. These are deliberately not the same thing — see the
+// StripeCouponGrant entity doc comment for the ownership boundary.
+
+import { request } from '../api.js';
+
+const BASE = '/BillingCouponGrant';
+
+function money(cents) {
+  return `$${(Number(cents) / 100).toFixed(2)}`;
+}
+
+function amount(g) {
+  return g.amountType === 'percent' ? `${g.amountValue}%` : `${money(g.amountValue)} ${String(g.currency).toUpperCase()}`;
+}
+
+function duration(g) {
+  switch (g.durationKind) {
+    case 'forever':    return 'forever';
+    case 'periods':    return `${g.durationMonths} billing period(s)`;
+    case 'once':       return 'one-time';
+    case 'trial_only': return 'trial-only (expires unused if not applied during the trial)';
+    case 'until_date': return `until ${g.expiresAtUtc}`;
+    default:           return g.durationKind;
+  }
+}
+
+function scope(g) {
+  return g.scope === 'account' ? 'whole account' : `${g.scope}: ${g.scopeTargetPriceId}`;
+}
+
+// How the discount is actually enforced. Not every Velaro account is charged via Stripe —
+// manually-invoiced and comped accounts get the discount recorded here for whoever bills them,
+// with no Stripe call made at all.
+function appliedVia(g) {
+  if (!g.appliedVia) return '(not applied yet)';
+  return g.appliedVia === 'manual_invoice'
+    ? 'manual invoice (account is not Stripe-billed; no Stripe coupon created)'
+    : 'Stripe coupon';
+}
+
+function line(g) {
+  const flag = g.isActive ? '*' : ' ';
+  return `${flag} [${g.id}] site ${g.siteId}  ${amount(g).padEnd(14)} ${String(g.status).padEnd(15)} ${scope(g).padEnd(28)} ${duration(g)}`;
+}
+
+async function list(args) {
+  const params = new URLSearchParams();
+  if (args.site) params.set('siteId', String(args.site));
+  if (args.all) params.set('includeTerminal', 'true');
+  const qs = params.toString();
+
+  const rows = await request('GET', qs ? `${BASE}?${qs}` : BASE);
+  if (!Array.isArray(rows) || rows.length === 0) {
+    console.log(args.all ? 'No discount grants found.' : 'No active discount grants. Use --all to include revoked/failed/expired.');
+    return;
+  }
+  console.log('  ID    SITE       AMOUNT         STATUS          SCOPE                        DURATION');
+  rows.forEach((g) => console.log(line(g)));
+  console.log(`\n${rows.length} grant(s). "*" = active (holds the account's one-discount slot).`);
+}
+
+async function get(id) {
+  const g = await request('GET', `${BASE}/${id}`);
+  console.log(`Grant #${g.id} — site ${g.siteId}`);
+  console.log(`  Name:            ${g.name}`);
+  console.log(`  Coupon code:     ${g.couponCode ?? '(none — ad-hoc grant)'}`);
+  console.log(`  Amount:          ${amount(g)}`);
+  console.log(`  Scope:           ${scope(g)}`);
+  console.log(`  Duration:        ${duration(g)}`);
+  console.log(`  Status:          ${g.status}${g.isActive ? ' (active)' : ''}`);
+  console.log(`  Applied via:     ${appliedVia(g)}`);
+  console.log(`  Stripe coupon:   ${g.stripeCouponId ?? '(not created yet)'}`);
+  console.log(`  Stripe sub:      ${g.stripeSubscriptionId ?? '(not resolved yet)'}`);
+  console.log(`  Stripe discount: ${g.stripeDiscountId ?? '(not attached yet)'}`);
+  console.log(`  Applied at:      ${g.appliedAtUtc ?? '(not applied)'}`);
+  console.log(`  Attempts:        ${g.attemptCount}`);
+  if (g.failureReason) console.log(`  Last failure:    ${g.failureReason}`);
+  if (g.notes)         console.log(`  Notes:           ${g.notes}`);
+  console.log(`  Created:         ${g.createdAtUtc} by ${g.createdBy}`);
+  if (g.revokedAtUtc)  console.log(`  Revoked:         ${g.revokedAtUtc} by ${g.revokedBy}`);
+}
+
+function buildBody(args) {
+  const body = {};
+  if (args.site !== undefined)     body.siteId = Number(args.site);
+  if (args.name !== undefined)     body.name = args.name;
+  if (args['coupon-code'])         body.couponCode = args['coupon-code'];
+  if (args.type !== undefined)     body.amountType = args.type;
+  if (args.value !== undefined)    body.amountValue = Number(args.value);
+  if (args.currency !== undefined) body.currency = args.currency;
+  if (args.scope !== undefined)    body.scope = args.scope;
+  if (args['scope-price'])         body.scopeTargetPriceId = args['scope-price'];
+  if (args.duration !== undefined) body.durationKind = args.duration;
+  if (args.months !== undefined)   body.durationMonths = Number(args.months);
+  if (args.expires !== undefined)  body.expiresAtUtc = args.expires;
+  if (args.notes !== undefined)    body.notes = args.notes;
+  return body;
+}
+
+async function create(args) {
+  if (!args.site || args.value === undefined) {
+    console.error('Usage: velaro coupon-grant create --site <siteId> --type percent|fixed --value <n> --duration forever|periods|once|trial_only|until_date [--months N] [--expires ISO] [--scope account|package|feature --scope-price <stripePriceId>] [--name "..."] [--coupon-code CODE] [--notes "..."]');
+    console.error('  --value is a percentage for --type percent, or WHOLE CENTS for --type fixed (5000 = $50.00).');
+    process.exit(1);
+  }
+
+  const g = await request('POST', BASE, buildBody(args));
+  console.log(`Created grant #${g.id} for site ${g.siteId}: ${amount(g)}, ${duration(g)}, ${scope(g)}.`);
+  console.log(`Status: ${g.status}. The Stripe side is attached by a background job — re-run "velaro coupon-grant get ${g.id}" in a moment to confirm it reached "applied".`);
+}
+
+async function update(args) {
+  if (!args.id) {
+    console.error('Usage: velaro coupon-grant update --id <grantId> [--name ...] [--type ...] [--value ...] [--duration ...] [--months N] [--expires ISO] [--scope ...] [--scope-price ...] [--notes ...]');
+    console.error('  Only a still-pending grant can be edited. Every field is optional — omitted fields are left untouched.');
+    process.exit(1);
+  }
+
+  const body = buildBody(args);
+  delete body.siteId; // a grant never moves between accounts
+  const g = await request('PUT', `${BASE}/${args.id}`, body);
+  console.log(`Updated grant #${g.id}: ${amount(g)}, ${duration(g)}, ${scope(g)}.`);
+}
+
+async function revoke(id) {
+  if (!id) {
+    console.error('Usage: velaro coupon-grant revoke <grantId>');
+    process.exit(1);
+  }
+  const g = await request('DELETE', `${BASE}/${id}`);
+  console.log(`Revoked grant #${g.id} for site ${g.siteId}. The Stripe discount has been removed and the account's discount slot is free again.`);
+}
+
+async function retry(id) {
+  if (!id) {
+    console.error('Usage: velaro coupon-grant retry <grantId>');
+    process.exit(1);
+  }
+  const g = await request('POST', `${BASE}/${id}/retry`);
+  console.log(`Re-created failed grant as #${g.id} (status ${g.status}). Check back with "velaro coupon-grant get ${g.id}".`);
+}
+
+export const couponGrantCommand = {
+  command: 'coupon-grant <subcommand>',
+  describe: "Manage per-account Stripe discount grants (Velaro billing staff only). One active discount per account.",
+  builder: (yargs) =>
+    yargs
+      .command('list', 'List discount grants', {
+        site: { type: 'number', describe: 'Filter to one site' },
+        all:  { type: 'boolean', default: false, describe: 'Include revoked/failed/expired grants' },
+      }, (args) => list(args))
+      .command('get <id>', 'Show one grant in full', {}, (args) => get(args.id))
+      .command('create', 'Grant a discount to one account', {
+        site:          { type: 'number', describe: 'Target site ID (required)' },
+        name:          { type: 'string', describe: 'Staff-facing label for why this was granted' },
+        'coupon-code': { type: 'string', describe: 'Audit link to a reusable code in the messaging coupon catalog' },
+        type:          { type: 'string', default: 'percent', describe: 'percent | fixed' },
+        value:         { type: 'number', describe: 'Percentage, or whole CENTS when --type fixed (required)' },
+        currency:      { type: 'string', default: 'usd', describe: 'Currency for a fixed amount' },
+        scope:         { type: 'string', default: 'account', describe: 'account | package | feature' },
+        'scope-price': { type: 'string', describe: 'Stripe Price ID the discount is limited to (required unless scope=account)' },
+        duration:      { type: 'string', default: 'once', describe: 'forever | periods | once | trial_only | until_date' },
+        months:        { type: 'number', describe: 'Billing periods, when --duration periods' },
+        expires:       { type: 'string', describe: 'ISO UTC cutoff, required when --duration until_date' },
+        notes:         { type: 'string', describe: 'Internal note' },
+      }, (args) => create(args))
+      .command('update', 'Edit a still-pending grant (partial update)', {
+        id:            { type: 'number', describe: 'Grant ID (required)' },
+        name:          { type: 'string' },
+        'coupon-code': { type: 'string' },
+        type:          { type: 'string' },
+        value:         { type: 'number' },
+        currency:      { type: 'string' },
+        scope:         { type: 'string' },
+        'scope-price': { type: 'string' },
+        duration:      { type: 'string' },
+        months:        { type: 'number' },
+        expires:       { type: 'string' },
+        notes:         { type: 'string' },
+      }, (args) => update(args))
+      .command('revoke <id>', "Remove a grant's discount from Stripe and free the account's slot", {}, (args) => revoke(args.id))
+      .command('retry <id>', 'Re-attempt a failed grant', {}, (args) => retry(args.id))
+      .demandCommand(1, 'Specify a subcommand: list | get | create | update | revoke | retry'),
+  handler: () => {},
+};

package/lib/commands/db.js

@@ -0,0 +1,101 @@
+import { runCommand } from '../run.js';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Direct database query tool — read-only by default.
+//
+// Built 2026-08-17 after a session burned significant time trying to answer
+// one question ("did migration X actually apply to staging?") through the
+// Azure Portal's browser-based Query Editor, which stopped responding to
+// clicks under host memory pressure. This is the durable replacement: a
+// scriptable, non-interactive way to run a SQL query against any of the
+// named databases below, with connection strings sourced from Key Vault
+// (never hardcoded) per this repo's KV-first secrets rule.
+//
+// SAFE BY DEFAULT: only SELECT statements are allowed unless --allow-write
+// is passed explicitly. This tool is for diagnostics, not migrations —
+// schema changes still go through `dotnet ef migrations add` per this
+// repo's EF-migrations-are-the-source-of-truth rule.
+// ────────────────────────────────────────────────────────────────────────────
+
+// Maps a short --db name to the Key Vault secret holding its connection string.
+// Add a new entry here (and set the secret in the vault) whenever a new
+// database needs to be queryable this way — never hardcode a connection
+// string in this file.
+const DB_SECRETS = {
+  kb: {
+    staging: { vault: 'velaro-eastus-stg-kv', secret: 'KnowledgeBaseConnectionString-Staging' },
+  },
+};
+
+async function getConnectionString(dbName, env, connectionStringFile) {
+  if (connectionStringFile) {
+    const { readFileSync } = await import('fs');
+    return readFileSync(connectionStringFile, 'utf8').trim();
+  }
+  const entry = DB_SECRETS[dbName]?.[env];
+  if (!entry) {
+    const known = Object.entries(DB_SECRETS)
+      .flatMap(([db, envs]) => Object.keys(envs).map((e) => `${db}/${e}`))
+      .join(', ');
+    throw new Error(`No connection string registered for --db ${dbName} --env ${env}. Known: ${known}. Or pass --connection-string-file for a one-off ad-hoc connection (never commit that file).`);
+  }
+  const { SecretClient } = await import('@azure/keyvault-secrets');
+  const { DefaultAzureCredential } = await import('@azure/identity');
+  const client = new SecretClient(`https://${entry.vault}.vault.azure.net`, new DefaultAzureCredential());
+  const secret = await client.getSecret(entry.secret);
+  return secret.value;
+}
+
+// Conservative guard: block anything that isn't a plain read. This is a
+// string check, not a real SQL parser — it exists to stop accidental writes
+// from a mistyped query, not to be airtight against a determined bypass.
+// Real write protection is the underlying SQL user's own grants.
+function assertReadOnly(query) {
+  const normalized = query.trim().replace(/^\s*;+/, '').toUpperCase();
+  const writeVerbs = ['INSERT', 'UPDATE', 'DELETE', 'DROP', 'ALTER', 'TRUNCATE', 'EXEC', 'MERGE', 'CREATE'];
+  const firstWord = normalized.split(/\s+/)[0];
+  if (writeVerbs.includes(firstWord)) {
+    throw new Error(`Query looks like a write (${firstWord}) — pass --allow-write to run it, or use a proper EF migration for schema changes.`);
+  }
+}
+
+export const dbCommand = {
+  command: 'db <subcommand>',
+  describe: 'Run direct SQL queries against a named database (diagnostics only — read-only unless --allow-write)',
+  builder: (yargs) =>
+    yargs
+      .command({
+        command: 'query <sql>',
+        describe: 'Run a SQL query. Wrap the query in quotes.',
+        builder: (y) =>
+          y
+            .positional('sql', { type: 'string', describe: 'SQL query to run' })
+            .option('db', { type: 'string', describe: `Database name (${Object.keys(DB_SECRETS).join(', ')})` })
+            .option('env', { type: 'string', default: 'staging', choices: ['staging', 'prod'], describe: 'Environment' })
+            .option('connection-string-file', { type: 'string', describe: 'Path to a local file containing a raw connection string, for one-off ad-hoc queries not yet registered in Key Vault' })
+            .option('allow-write', { type: 'boolean', default: false, describe: 'Allow INSERT/UPDATE/DELETE/DDL statements' }),
+        handler: runCommand(async (argv) => {
+          if (!argv['allow-write']) assertReadOnly(argv.sql);
+
+          const sql = await import('mssql');
+          const connectionString = await getConnectionString(argv.db, argv.env, argv['connection-string-file']);
+          const pool = await sql.default.connect(connectionString);
+          try {
+            const result = await pool.request().query(argv.sql);
+            const rows = Array.isArray(result.recordset) ? result.recordset : [];
+            if (rows.length === 0) {
+              console.log(argv['allow-write']
+                ? `Done. Rows affected: ${result.rowsAffected?.join(', ') ?? 0}`
+                : 'No rows returned.');
+              return;
+            }
+            console.table(rows);
+            console.log(`\n${rows.length} row(s).`);
+          } finally {
+            await pool.close();
+          }
+        }),
+      })
+      .demandCommand(1, 'Specify: query'),
+  handler: () => {},
+};