@sitar_fiercer4c/skills 0.1.0

package/skills/record-api-traffic/scripts/check-schema.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Does the app still look the way the dump scripts assume?
+//
+//   node check-schema.mjs --repo <repo> [--json]
+//
+// The dump scripts moved out of the app repo, so nothing makes them travel
+// with a schema change any more. A renamed field would not crash: findById()
+// still returns a document, `quotation.sourceWorkbookBuffer` is just
+// undefined, and dump-source-excel silently falls through to the Graph
+// refetch — or writes a zero-byte file. This check turns that into a loud
+// failure before a session starts.
+//
+// Exit codes:  0 = aligned    1 = drift    2 = cannot verify
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { importRepo, importDependency } from './lib/repo.mjs';
+
+// Every field the two dump scripts touch, and what it costs if it moves.
+const FIELDS = [
+  ['sourceWorkbookBuffer', true, 'Buffer',
+    'dump-source-excel reads the xlsx bytes from here'],
+  ['sourceAttachmentName', true, 'String',
+    'names the dumped file and supplies its extension'],
+  ['sourceFileType', true, 'String',
+    'extension fallback when the attachment name has none'],
+  ['user', true, null,
+    'first argument to getAttachmentBuffer on the refetch path'],
+  ['sourceMessageId', true, 'String', 'identifies the mail to refetch from'],
+  ['sourceAttachmentId', true, 'String', 'identifies the attachment to refetch'],
+  ['referenceNumber', false, 'String', 'summary label'],
+  ['title', false, 'String', 'summary label fallback'],
+  ['status', false, 'String', 'printed in the summary'],
+  ['quotationItems', false, 'Array', 'item count in the summary'],
+];
+
+const checks = [];
+const add = (status, name, detail) => checks.push({ status, name, detail });
+
+function parse() {
+  const args = process.argv.slice(2);
+  let repo = null;
+  let json = false;
+  let probeEmail = false;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--repo') { repo = args[i + 1]; i += 1; }
+    else if (args[i].startsWith('--repo=')) repo = args[i].slice(7);
+    else if (args[i] === '--json') json = true;
+    else if (args[i] === '--probe-email') probeEmail = true;
+  }
+  if (!repo) {
+    console.error('Usage: node check-schema.mjs --repo <repo> [--json]');
+    process.exit(2);
+  }
+  return { repo: path.resolve(repo), json, probeEmail };
+}
+
+// email.service pulls in ~20 modules (S3, pdf, datalab). An import-time throw
+// is catchable, but an import-time process.exit would take the whole check
+// down with it, so probe it in a child.
+async function probeEmail(backend) {
+  try {
+    const mod = await importRepo(backend, 'src/services/email.service.js');
+    const fn = mod.default?.getAttachmentBuffer;
+    if (typeof fn !== 'function') {
+      return { status: 'FAIL', detail: 'default export has no getAttachmentBuffer()' };
+    }
+    if (fn.length !== 3) {
+      return {
+        status: 'FAIL',
+        detail: `getAttachmentBuffer takes ${fn.length} args, expected 3 `
+          + '(userId, messageId, attachmentId)',
+      };
+    }
+    return { status: 'ok', detail: 'getAttachmentBuffer(userId, messageId, attachmentId)' };
+  } catch (err) {
+    return { status: 'warn', detail: `could not load: ${err.message}` };
+  }
+}
+
+async function main() {
+  const { repo, json, probeEmail: isProbe } = parse();
+  const backend = path.join(repo, 'Backend');
+
+  if (isProbe) {
+    console.log(JSON.stringify(await probeEmail(backend)));
+    return 0;
+  }
+
+  if (!fs.existsSync(backend)) {
+    console.error(`Not an app repo (no Backend/): ${repo}`);
+    return 2;
+  }
+  if (!fs.existsSync(path.join(backend, 'node_modules'))) {
+    if (json) {
+      console.log(JSON.stringify({
+        verifiable: false,
+        reason: 'Backend/node_modules missing; the model cannot be loaded',
+        checks: [],
+      }, null, 2));
+    } else {
+      console.log('\n  Cannot verify: Backend/node_modules missing.\n');
+    }
+    return 2;
+  }
+
+  let Quotation;
+  try {
+    Quotation = (await importRepo(backend, 'src/models/quotation.model.js')).default;
+  } catch (err) {
+    add('FAIL', 'quotation model', `cannot load src/models/quotation.model.js: ${err.message}`);
+  }
+
+  if (Quotation) {
+    if (!Quotation.schema) {
+      add('FAIL', 'quotation model', 'default export is not a Mongoose model');
+    } else {
+      for (const [field, required, expected, why] of FIELDS) {
+        const schemaPath = Quotation.schema.path(field);
+        if (!schemaPath) {
+          add(required ? 'FAIL' : 'warn', `field ${field}`,
+            `missing from the schema — ${why}`);
+        } else if (expected && schemaPath.instance !== expected) {
+          add(required ? 'FAIL' : 'warn', `field ${field}`,
+            `is ${schemaPath.instance}, expected ${expected} — ${why}`);
+        } else {
+          add('ok', `field ${field}`, schemaPath.instance || 'present');
+        }
+      }
+    }
+  }
+
+  try {
+    const connectDB = (await importRepo(backend, 'src/config/db.js')).default;
+    if (typeof connectDB !== 'function') {
+      add('FAIL', 'db.js', 'default export is not a function');
+    } else {
+      add('ok', 'db.js', 'default export is connectDB()');
+    }
+  } catch (err) {
+    add('FAIL', 'db.js', `cannot load src/config/db.js: ${err.message}`);
+  }
+
+  const child = spawnSync(process.execPath,
+    [fileURLToPath(import.meta.url), '--repo', repo, '--probe-email'],
+    { encoding: 'utf8', timeout: 60000 });
+  let emailResult;
+  try {
+    emailResult = JSON.parse(child.stdout.trim().split('\n').at(-1));
+  } catch {
+    emailResult = {
+      status: 'warn',
+      detail: `probe did not report (exit ${child.status}): `
+        + `${(child.stderr || '').trim().split('\n').at(-1) || 'no output'}`,
+    };
+  }
+  add(emailResult.status, 'email.service', emailResult.detail);
+
+  const failures = checks.filter((c) => c.status === 'FAIL');
+  const warnings = checks.filter((c) => c.status === 'warn');
+
+  if (json) {
+    console.log(JSON.stringify({
+      verifiable: true, aligned: !failures.length, checks,
+    }, null, 2));
+  } else {
+    const width = Math.max(...checks.map((c) => c.name.length));
+    console.log(`\n  SCHEMA ALIGNMENT — dump scripts vs ${repo}\n`);
+    for (const c of checks) {
+      console.log(`  ${c.status.padEnd(4)}  ${c.name.padEnd(width)}  ${c.detail}`);
+    }
+    console.log(failures.length
+      ? `\n  ${failures.length} mismatch(es). The dump scripts need updating before use.\n`
+      : `\n  Aligned${warnings.length ? ` (${warnings.length} warning(s))` : ''}.\n`);
+  }
+
+  return failures.length ? 1 : 0;
+}
+
+main().then((code) => process.exit(code)).catch((err) => {
+  console.error('FATAL:', err.message);
+  process.exit(2);
+});

package/skills/record-api-traffic/scripts/dump-quotation.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Dump a quotation document verbatim from MongoDB, so a recording session has
+// its real output alongside the API traffic. Unlike GET /api/quotations/:id
+// this is the stored document, not the API's serialisation of it.
+//
+//   node dump-quotation.mjs --repo <repo> <quotationId> [runDir]
+//
+// Writes into the skill's own recordings workspace, never into the repo.
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  parseArgs, artifactsDir, loadEnv, importRepo, importDependency,
+} from './lib/repo.mjs';
+
+const USAGE = 'node dump-quotation.mjs --repo <repo> <quotationId> [runDir]';
+const { repo, backend, positional } = parseArgs(process.argv, USAGE);
+const [quotationId, runDir] = positional;
+if (!quotationId) {
+  console.error(`Usage: ${USAGE}`);
+  process.exit(1);
+}
+
+loadEnv(backend);
+const mongoose = (await importDependency(backend, 'mongoose')).default;
+const connectDB = (await importRepo(backend, 'src/config/db.js')).default;
+const Quotation = (await importRepo(backend, 'src/models/quotation.model.js')).default;
+
+async function main() {
+  const outDir = artifactsDir(repo, runDir);
+
+  await connectDB();
+
+  const quotation = await Quotation.findById(quotationId).lean();
+  if (!quotation) {
+    console.error(`No quotation ${quotationId}`);
+    process.exit(1);
+  }
+
+  // Megabytes of xlsx bytes would make the JSON unreadable; dump-source-excel.mjs
+  // writes them out as a real file instead.
+  // lean() skips Mongoose casting, so a Buffer field arrives as a BSON Binary
+  // whose .length is a method rather than a byte count.
+  const raw = quotation.sourceWorkbookBuffer;
+  const bufferBytes = raw ? (Buffer.isBuffer(raw) ? raw.length : raw.length()) : 0;
+  quotation.sourceWorkbookBuffer = bufferBytes
+    ? { bytes: bufferBytes, note: 'see dump-source-excel.mjs' }
+    : null;
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const outPath = path.join(outDir, `${quotationId}.json`);
+  const json = JSON.stringify(quotation, null, 2);
+  fs.writeFileSync(outPath, json);
+
+  console.log(`\n  ${quotation.referenceNumber || quotation.title || '(untitled)'}`);
+  console.log(`  status : ${quotation.status}`);
+  console.log(`  items  : ${quotation.quotationItems?.length ?? 0}`);
+  console.log(`  size   : ${json.length} bytes of JSON (+ ${bufferBytes} bytes of xlsx omitted)`);
+  console.log(`  written: ${outPath}\n`);
+
+  await mongoose.connection.close();
+}
+
+main().catch(async (err) => {
+  console.error('FATAL:', err.message);
+  await mongoose.connection.close().catch(() => {});
+  process.exit(1);
+});

package/skills/record-api-traffic/scripts/dump-source-excel.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Dump the original attachment a quotation was built from, so a recording
+// session has its real input alongside the API traffic.
+//
+//   node dump-source-excel.mjs --repo <repo> <quotationId> [runDir]
+//
+// Writes into the skill's own recordings workspace, never into the repo.
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  parseArgs, artifactsDir, loadEnv, importRepo, importDependency,
+} from './lib/repo.mjs';
+
+const USAGE = 'node dump-source-excel.mjs --repo <repo> <quotationId> [runDir]';
+const { repo, backend, positional } = parseArgs(process.argv, USAGE);
+const [quotationId, runDir] = positional;
+if (!quotationId) {
+  console.error(`Usage: ${USAGE}`);
+  process.exit(1);
+}
+
+loadEnv(backend);
+const mongoose = (await importDependency(backend, 'mongoose')).default;
+const connectDB = (await importRepo(backend, 'src/config/db.js')).default;
+const Quotation = (await importRepo(backend, 'src/models/quotation.model.js')).default;
+
+async function main() {
+  const outDir = artifactsDir(repo, runDir);
+
+  await connectDB();
+
+  const quotation = await Quotation.findById(quotationId).lean();
+  if (!quotation) {
+    console.error(`No quotation ${quotationId}`);
+    process.exit(1);
+  }
+
+  // lean() skips Mongoose casting, so a Buffer field arrives as a BSON Binary
+  // whose .length is a method — every size check below would misread it.
+  let buffer = quotation.sourceWorkbookBuffer;
+  if (buffer && !Buffer.isBuffer(buffer)) buffer = Buffer.from(buffer.buffer ?? buffer);
+  let source = 'mongo (sourceWorkbookBuffer)';
+
+  // Null for CSV attachments, legacy quotations, and documents that hit the
+  // BSON size cap — the buffer is the first field dropped there. email.service
+  // drags in most of the backend, so only load it if this path is taken.
+  if (!buffer?.length) {
+    console.log('sourceWorkbookBuffer empty, refetching from Outlook...');
+    const emailService = (await importRepo(backend, 'src/services/email.service.js')).default;
+    ({ buffer } = await emailService.getAttachmentBuffer(
+      quotation.user,
+      quotation.sourceMessageId,
+      quotation.sourceAttachmentId
+    ));
+    source = 'microsoft graph';
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const ext = path.extname(quotation.sourceAttachmentName) || `.${quotation.sourceFileType}`;
+  const outPath = path.join(outDir, `${quotationId}-source${ext}`);
+  fs.writeFileSync(outPath, buffer);
+
+  console.log(`\n  ${quotation.sourceAttachmentName}`);
+  console.log(`  from   : ${source}`);
+  console.log(`  bytes  : ${buffer.length}`);
+  console.log(`  written: ${outPath}\n`);
+
+  await mongoose.connection.close();
+}
+
+main().catch(async (err) => {
+  console.error('FATAL:', err.message);
+  await mongoose.connection.close().catch(() => {});
+  process.exit(1);
+});

package/skills/record-api-traffic/scripts/lib/repo.mjs

@@ -0,0 +1,109 @@
+// Helpers for running app-repo code from outside the app repo.
+//
+// These scripts live in the skill, not in the repo they operate on, so no
+// bare specifier resolves: `import mongoose` here would look in the skill's
+// own (nonexistent) node_modules. Everything is resolved explicitly from the
+// repo path instead.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const SKILL = path.resolve(import.meta.dirname, '../..');
+export const WORKSPACE = path.join(SKILL, '..', 'record-api-traffic-workspace', 'recordings');
+
+export function parseArgs(argv, usage) {
+  const args = argv.slice(2);
+  const positional = [];
+  let repo = null;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--repo') {
+      repo = args[i + 1];
+      i += 1;
+    } else if (args[i].startsWith('--repo=')) {
+      repo = args[i].slice(7);
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  if (!repo) {
+    console.error(`Usage: ${usage}`);
+    process.exit(1);
+  }
+  repo = path.resolve(repo);
+  if (!fs.existsSync(path.join(repo, 'Backend'))) {
+    console.error(`Not an app repo (no Backend/): ${repo}`);
+    process.exit(1);
+  }
+  return { repo, backend: path.join(repo, 'Backend'), positional };
+}
+
+// Mirrors workspace_slug() in record-api-traffic.py: the last two path
+// segments, so two clones of the same repo get separate recording folders.
+export function workspaceSlug(repo) {
+  return repo
+    .split(path.sep)
+    .filter(Boolean)
+    .slice(-2)
+    .join('-')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+// Artifacts belong beside the traffic they came from, so default to the
+// newest run folder for this repo. Pass a run dir to target an older session.
+export function artifactsDir(repo, explicit) {
+  if (explicit) return path.resolve(explicit, 'artifacts');
+  const base = path.join(WORKSPACE, workspaceSlug(repo));
+  const runs = fs.existsSync(base)
+    ? fs.readdirSync(base, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name.startsWith('run-'))
+        .map((e) => e.name)
+        .sort()
+    : [];
+  if (!runs.length) {
+    console.error(`No recordings for ${repo} under ${base}. Record a session first, `
+      + 'or pass a run directory explicitly.');
+    process.exit(1);
+  }
+  return path.join(base, runs.at(-1), 'artifacts');
+}
+
+// The repo's db.js reads process.env, and its dotenv.config() resolves .env
+// from the working directory -- which is the skill, not the repo. Load it
+// here so the scripts work from anywhere. dotenv does not override existing
+// values, so these win.
+export function loadEnv(backend) {
+  const file = path.join(backend, '.env');
+  if (!fs.existsSync(file)) {
+    console.error(`Missing ${file}`);
+    process.exit(1);
+  }
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) continue;
+    const eq = trimmed.indexOf('=');
+    const key = trimmed.slice(0, eq).trim().replace(/^export\s+/, '');
+    let value = trimmed.slice(eq + 1).trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.endsWith(quote)) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+export function importRepo(backend, relative) {
+  const file = path.join(backend, relative);
+  if (!fs.existsSync(file)) throw new Error(`missing ${file}`);
+  return import(pathToFileURL(file).href);
+}
+
+// Bare specifiers resolve from the importing file's directory, so ask Node to
+// resolve them as if from inside the repo, then import the resulting path.
+export function importDependency(backend, specifier) {
+  const require = createRequire(path.join(backend, 'package.json'));
+  return import(pathToFileURL(require.resolve(specifier)).href);
+}