mandrel 1.57.0

package/.agents/scripts/lib/audit-suite/runner.js

@@ -0,0 +1,233 @@
+/**
+ * lib/audit-suite/runner.js — `runAuditSuite` aggregation core.
+ *
+ * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
+ *
+ * The runner composes the focused helpers from this directory:
+ *   - frontmatter.js     → `summarizeWorkflow`
+ *   - substitutions.js   → `applySubstitutions`, `computeAllowedKeys`
+ *   - findings.js        → `aggregateSummary`
+ *   - workflow-loader.js → `loadWorkflow`, `defaultWriteArtifact`
+ *
+ * It owns the audit envelope shape (`metadata`, `findings`, `workflows`) and
+ * the per-audit fan-out + result reduction. The CLI entry-point in
+ * `.agents/scripts/run-audit-suite.js` reduces to argument parsing and
+ * stdout/stderr glue around this function.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
+import { ValidationError } from '../errors/index.js';
+import { aggregateSummary } from './findings.js';
+import { summarizeWorkflow } from './frontmatter.js';
+import { applySubstitutions, computeAllowedKeys } from './substitutions.js';
+import { defaultWriteArtifact, loadWorkflow } from './workflow-loader.js';
+
+async function loadRules(paths) {
+  const rulesPath = path.join(
+    PROJECT_ROOT,
+    paths.schemasRoot,
+    'audit-rules.json',
+  );
+  const rulesContent = await fs.readFile(rulesPath, 'utf8');
+  return JSON.parse(rulesContent);
+}
+
+function rejectUnknownKeys(allowedKeys, callerSubstitutions) {
+  const unknownKeys = Object.keys(callerSubstitutions).filter(
+    (k) => !allowedKeys.has(k),
+  );
+  if (unknownKeys.length === 0) return;
+  const allowedList = [...allowedKeys].sort().join(', ');
+  throw new ValidationError(
+    `Unknown substitution key(s): ${unknownKeys.join(', ')}. Allowed for this call: ${allowedList}.`,
+    { unknownKeys, allowedKeys: [...allowedKeys] },
+  );
+}
+
+function emptyEnvelope(auditWorkflows) {
+  return {
+    metadata: {
+      timestamp: new Date().toISOString(),
+      auditsRequested: auditWorkflows,
+      auditsRun: [],
+      summary: { critical: 0, high: 0, medium: 0, low: 0 },
+    },
+    findings: [],
+    workflows: [],
+  };
+}
+
+function notDefinedFinding(auditName) {
+  return {
+    error: true,
+    finding: {
+      audit: auditName,
+      severity: 'low',
+      message: `Requested audit workflow '${auditName}' is not defined in audit-rules.json.`,
+    },
+  };
+}
+
+function notFoundFinding(auditName) {
+  return {
+    error: true,
+    finding: {
+      audit: auditName,
+      severity: 'low',
+      message: `Audit workflow '${auditName}.md' not found in workflows directory.`,
+    },
+  };
+}
+
+async function processAudit({
+  auditName,
+  validAudits,
+  loader,
+  workflowsDir,
+  effectiveSubstitutions,
+}) {
+  if (!validAudits.includes(auditName)) {
+    return notDefinedFinding(auditName);
+  }
+
+  const workflow = await loader(auditName, workflowsDir);
+  if (!workflow) {
+    return notFoundFinding(auditName);
+  }
+
+  const substituted = applySubstitutions(
+    workflow.content,
+    effectiveSubstitutions,
+  );
+
+  return {
+    success: true,
+    auditName,
+    workflowPath: workflow.path ?? null,
+    workflowContent: substituted,
+    summary: summarizeWorkflow(workflow.content),
+    byteSize: Buffer.byteLength(substituted, 'utf8'),
+  };
+}
+
+async function reduceResults({
+  results,
+  envelope,
+  artifactPrefix,
+  effectiveArtifactsDir,
+  writeArtifact,
+}) {
+  for (const result of results) {
+    if (result.error) {
+      envelope.findings.push(result.finding);
+      continue;
+    }
+    if (!result.success) continue;
+
+    envelope.metadata.auditsRun.push(result.auditName);
+    let artifactPath = null;
+    if (artifactPrefix) {
+      const fileName = `audit-${artifactPrefix}-${result.auditName}.md`;
+      artifactPath = await writeArtifact(
+        effectiveArtifactsDir,
+        fileName,
+        result.workflowContent,
+      );
+    }
+    envelope.workflows.push({
+      audit: result.auditName,
+      path: result.workflowPath,
+      summary: result.summary,
+      byteSize: result.byteSize,
+      artifactPath,
+    });
+  }
+}
+
+/**
+ * Run a suite of named audit workflows.
+ *
+ * For each audit name the suite will:
+ *   1. Validate it is registered in audit-rules.json.
+ *   2. Locate the corresponding `.agents/workflows/<auditName>.md` file.
+ *   3. Return a slim `workflow` descriptor (audit name, source path, summary,
+ *      byte size) for the calling AI agent. Full prompt bodies are written to
+ *      `<auditOutputDir>/audit-<runId>-<audit>.md` (resolved from
+ *      `project.paths.tempRoot`, default `temp/audits/`) when `artifactPrefix`
+ *      (or `runId`) is provided, so downstream agents can read them locally
+ *      without bloating the GitHub comment surface.
+ *
+ * Substitutions: callers may pass a `substitutions` map of `{{key}}` → value
+ * pairs. Allowed keys are the built-ins (auditOutputDir, ticketId, baseBranch,
+ * changedFiles) plus any `substitutionKeys` declared on the requested audits in
+ * audit-rules.json, aggregated across auditWorkflows. Unknown keys
+ * raise a ValidationError.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.auditWorkflows - List of audit names to run.
+ * @param {Record<string,string>} [opts.substitutions] - Optional template substitutions.
+ * @param {string} [opts.artifactPrefix] - When set, write full bodies to
+ *   `<artifactsDir>/audit-<artifactPrefix>-<audit>.md`.
+ * @param {string} [opts.artifactsDir] - Override the artifacts directory
+ *   (default: `<PROJECT_ROOT>/<auditOutputDir>`, which resolves to
+ *   `<tempRoot>/audits` — `temp/audits` with default config).
+ * @param {Function} [opts.injectedLoadWorkflow] - Optional override for testing.
+ * @param {object} [opts.injectedRules] - Optional override for the audit-rules content (testing).
+ * @param {Function} [opts.injectedWriteArtifact] - Optional override for filesystem-free testing.
+ * @returns {Promise<object>} Aggregated audit results.
+ */
+export async function runAuditSuite({
+  auditWorkflows,
+  substitutions,
+  artifactPrefix,
+  artifactsDir,
+  injectedLoadWorkflow,
+  injectedRules,
+  injectedWriteArtifact,
+}) {
+  const { agentSettings } = resolveConfig();
+  const paths = getPaths({ agentSettings });
+  const callerSubstitutions = substitutions ?? {};
+  const rules = injectedRules ?? (await loadRules(paths));
+
+  const allowedKeys = computeAllowedKeys(rules, auditWorkflows);
+  rejectUnknownKeys(allowedKeys, callerSubstitutions);
+
+  const effectiveSubstitutions = {
+    auditOutputDir: paths.auditOutputDir,
+    ...callerSubstitutions,
+  };
+
+  const validAudits = Object.keys(rules.audits || {});
+  const envelope = emptyEnvelope(auditWorkflows);
+  const workflowsDir = path.join(PROJECT_ROOT, paths.workflowsRoot);
+  const effectiveArtifactsDir =
+    artifactsDir ?? path.join(PROJECT_ROOT, paths.auditOutputDir);
+  const writeArtifact = injectedWriteArtifact ?? defaultWriteArtifact;
+  const loader = injectedLoadWorkflow ?? loadWorkflow;
+
+  const results = await Promise.all(
+    auditWorkflows.map((auditName) =>
+      processAudit({
+        auditName,
+        validAudits,
+        loader,
+        workflowsDir,
+        effectiveSubstitutions,
+      }),
+    ),
+  );
+
+  await reduceResults({
+    results,
+    envelope,
+    artifactPrefix,
+    effectiveArtifactsDir,
+    writeArtifact,
+  });
+
+  envelope.metadata.summary = aggregateSummary(envelope.findings);
+  return envelope;
+}

package/.agents/scripts/lib/audit-suite/selector.js

@@ -0,0 +1,235 @@
+/**
+ * lib/audit-suite/selector.js — `selectAudits` rule-matching core.
+ *
+ * Extracted from `.agents/scripts/select-audits.js` (Story #1083, Epic
+ * #1072) so the audit-suite SDK barrel at `./index.js` can re-export it
+ * without importing upward from a top-level CLI file.
+ *
+ * Pure (modulo `gitSpawn`) — exposed helpers are:
+ *   - matchesFilePattern    — single file × single glob (picomatch with `dot`)
+ *   - matchesAnyFilePattern — file list × pattern list, short-circuiting
+ *   - selectAudits          — main entry; reads audit-rules.json, runs `git
+ *                             diff --name-only`, applies keyword + glob rules.
+ *
+ * The CLI wrapper at `.agents/scripts/select-audits.js` reduces to argv
+ * parsing, provider construction, JSON stdout, and degraded-mode exit-code
+ * mapping. All rule-matching lives here.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
+import { softFailOrThrow } from '../degraded-mode.js';
+import { gitSpawn } from '../git-utils.js';
+import { withTimeout } from '../util/with-timeout.js';
+
+const DEFAULT_GIT_TIMEOUT_MS = 30000;
+
+/**
+ * Test a single filename against a single glob pattern using the project's
+ * configured matcher semantics (`picomatch` with `dot: true`). Exported so
+ * regression tests can pin engine behaviour without stubbing audit-rules.
+ */
+export function matchesFilePattern(pattern, file) {
+  return picomatch(pattern, { dot: true })(file);
+}
+
+/**
+ * Return true when any of `files` matches any of `patterns`.
+ * Same semantics as `matchesFilePattern`; matchers are compiled once per call.
+ */
+export function matchesAnyFilePattern(patterns, files) {
+  if (!patterns?.length || !files?.length) return false;
+  const matchers = patterns.map((p) => picomatch(p, { dot: true }));
+  return files.some((file) => matchers.some((m) => m(file)));
+}
+
+/**
+ * Filter audits based on logic in audit-rules.json (validated against
+ * audit-rules.schema.json).
+ *
+ * @param {object} params
+ * @param {number} params.ticketId
+ * @param {string} params.gate
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} params.provider
+ * @param {string} [params.baseBranch]
+ * @param {string} [params.headRef]
+ *   Git ref whose diff-against-`baseBranch` defines the change set. Defaults
+ *   to `HEAD` (the working-copy tip) for ticket-scoped callers. Epic-mode
+ *   callers MUST pass the requested Epic's own branch ref (e.g.
+ *   `refs/heads/epic/<id>`) so the change set is pinned to that Epic's branch
+ *   rather than whatever HEAD the shared checkout happens to sit on. Under two
+ *   concurrent `/epic-deliver` runs sharing one checkout, diffing against
+ *   `HEAD` silently resolves the *other* Epic's change set (Story #3362). When
+ *   `headRef` cannot be resolved in the repo, the selector returns a
+ *   `degraded: true` envelope (or hard-fails in gate-mode) instead of diffing
+ *   the wrong tree.
+ * @param {(cwd: string, ...args: string[]) => Promise<{status:number, stdout:string, stderr:string}>} [params.injectedGitSpawn]
+ *   Test-only seam. Production callers leave unset; the real (synchronous) `gitSpawn`
+ *   is wrapped in `Promise.resolve` so `withTimeout` can still race it. Tests can
+ *   inject a promise that never resolves to exercise the ETIMEDOUT fallback.
+ * @param {number} [params.gitTimeoutMsOverride]
+ *   Test-only seam to shrink the git-spawn timeout below the configured default
+ *   (which is 30_000 ms) so timeout tests don't stall the suite.
+ * @param {{ argv?: string[], env?: NodeJS.ProcessEnv }} [params.gateModeOpts]
+ *   Test-only seam to drive the `--gate-mode` / `MANDREL_GATE_MODE=1`
+ *   detection; production callers leave unset and `isGateMode` reads
+ *   `process.argv` / `process.env`.
+ *
+ * Returns either the success envelope (`{ selectedAudits, ticketId, gate, context }`)
+ * OR the degraded envelope (`{ ok: false, degraded: true, reason, detail }`)
+ * when the git-diff probe times out OR `headRef` cannot be resolved and
+ * gate-mode is unset. In gate-mode, the same conditions throw.
+ */
+export async function selectAudits({
+  ticketId,
+  gate,
+  provider,
+  baseBranch = 'main',
+  headRef = 'HEAD',
+  injectedGitSpawn,
+  gitTimeoutMsOverride,
+  gateModeOpts,
+}) {
+  const { agentSettings } = resolveConfig();
+  const timeoutMs = gitTimeoutMsOverride ?? DEFAULT_GIT_TIMEOUT_MS;
+
+  const rulesPath = path.join(
+    PROJECT_ROOT,
+    getPaths({ agentSettings }).schemasRoot,
+    'audit-rules.json',
+  );
+  let rulesData;
+  try {
+    rulesData = JSON.parse(await fs.readFile(rulesPath, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `Failed to read audit-rules from ${rulesPath}: ${err.message}`,
+    );
+  }
+
+  const ticket = await provider.getTicket(ticketId);
+  const contentToSearch =
+    `${ticket.title || ''} ${ticket.body || ''}`.toLowerCase();
+
+  const runGit = injectedGitSpawn ?? (async (...args) => gitSpawn(...args));
+
+  // Resolve `headRef` to a commit before diffing. A non-default `headRef`
+  // (Epic-mode callers pass `refs/heads/epic/<id>`) that the repo can't
+  // resolve means the requested Epic's branch is not present in this
+  // checkout — diffing `baseBranch...HEAD` would silently report a
+  // *different* Epic's change set (Story #3362). Surface that as an explicit
+  // degraded signal instead of leaking the wrong scope. `HEAD` is always
+  // resolvable in a valid repo, so the default-path callers skip the probe
+  // cost on the common case.
+  if (headRef !== 'HEAD') {
+    let resolved;
+    try {
+      resolved = await withTimeout(
+        runGit(process.cwd(), 'rev-parse', '--verify', '--quiet', headRef),
+        timeoutMs,
+        { label: 'select-audits rev-parse headRef' },
+      );
+    } catch (err) {
+      if (err?.code === 'ETIMEDOUT') {
+        return softFailOrThrow(
+          'GIT_DIFF_TIMEOUT',
+          `select-audits: git rev-parse ${headRef} timed out after ${timeoutMs} ms`,
+          gateModeOpts,
+        );
+      }
+      throw err;
+    }
+    if (resolved?.status !== 0 || !resolved.stdout.trim()) {
+      return softFailOrThrow(
+        'HEAD_REF_UNRESOLVED',
+        `select-audits: requested ref '${headRef}' could not be resolved in this checkout; refusing to diff against a phantom change set`,
+        gateModeOpts,
+      );
+    }
+  }
+
+  let changedFiles = [];
+  try {
+    const diff = await withTimeout(
+      runGit(
+        process.cwd(),
+        'diff',
+        '--name-only',
+        `${baseBranch}...${headRef}`,
+      ),
+      timeoutMs,
+      { label: 'select-audits git diff' },
+    );
+    if (diff?.status === 0) {
+      changedFiles = diff.stdout
+        .split('\n')
+        .map((f) => f.trim())
+        .filter(Boolean);
+    }
+  } catch (err) {
+    if (err?.code === 'ETIMEDOUT') {
+      // Soft-fail contract (Tech Spec #819): in default mode, return a
+      // degraded envelope so the caller sees the explicit signal instead of
+      // silently falling through to keyword-only matching. In gate-mode,
+      // hard-fail closed.
+      return softFailOrThrow(
+        'GIT_DIFF_TIMEOUT',
+        `select-audits: git diff against ${baseBranch} timed out after ${timeoutMs} ms`,
+        gateModeOpts,
+      );
+    }
+    throw err;
+  }
+
+  const selectedAudits = [];
+
+  for (const [auditName, ruleOpts] of Object.entries(rulesData.audits || {})) {
+    const triggers = ruleOpts.triggers || {};
+
+    const gateMatch = triggers.gates?.includes(gate);
+    if (!gateMatch) continue;
+
+    if (triggers.alwaysRun) {
+      selectedAudits.push(auditName);
+      continue;
+    }
+
+    const keywords = triggers.keywords || [];
+    let keywordMatch = false;
+    for (const kw of keywords) {
+      if (contentToSearch.includes(kw.toLowerCase())) {
+        keywordMatch = true;
+        break;
+      }
+    }
+
+    const fileMatch = matchesAnyFilePattern(
+      triggers.filePatterns || [],
+      changedFiles,
+    );
+
+    if (keywordMatch || fileMatch) {
+      selectedAudits.push(auditName);
+    }
+  }
+
+  return {
+    selectedAudits,
+    ticketId,
+    gate,
+    context: {
+      // Full file list, exposed so Epic-mode callers (e.g. epic-audit) can
+      // pass it through as the {{changedFiles}} substitution value. Existing
+      // callers that read only `changedFilesCount` remain unaffected.
+      changedFiles,
+      changedFilesCount: changedFiles.length,
+      // The ref the change set was actually diffed against. Epic-mode callers
+      // assert this matches the requested Epic branch (Story #3362) so a
+      // mis-pinned diff never reaches the audit-lens selector silently.
+      resolvedRef: headRef,
+      ticketTitle: ticket.title,
+    },
+  };
+}

package/.agents/scripts/lib/audit-suite/substitutions.js

@@ -0,0 +1,124 @@
+/**
+ * lib/audit-suite/substitutions.js — `{{key}}` template substitution helpers.
+ *
+ * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
+ *
+ * Three concerns live here:
+ *   1. `applySubstitutions` — pure string templating used on each workflow body.
+ *   2. `parseSubstitutionPairs` / `applyImplicitSubstitutions` — CLI-side glue
+ *      that turns `--substitution key=value` pairs and `--ticket` / `--base-branch`
+ *      flags into the substitutions map the runner consumes.
+ *   3. `computeAllowedKeys` — the per-run allow-list (built-ins ∪ rule-declared
+ *      keys) used by the runner to reject unknown caller substitutions before
+ *      any workflow is loaded.
+ *
+ * No filesystem, no provider, no validation throws beyond `parseSubstitutionPairs`
+ * (which is defensive against malformed CLI input).
+ */
+
+import { ValidationError } from '../errors/index.js';
+
+/**
+ * Built-in substitution keys that are always available regardless of which
+ * audits are requested. `auditOutputDir` is sourced from the resolved paths;
+ * `ticketId` and `baseBranch` are populated from CLI flags or caller args.
+ */
+export const BUILT_IN_SUBSTITUTION_KEYS = Object.freeze([
+  'auditOutputDir',
+  'ticketId',
+  'baseBranch',
+  // Newline-joined change-set file list, populated by Epic-mode callers
+  // (e.g. `epic-audit`) from `selectAudits().context.changedFiles`.
+  // Absent in manual `/audit-*` invocations — lens templates handle the
+  // unsubstituted literal as "no scope filter".
+  'changedFiles',
+]);
+
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Pure: replace every occurrence of `{{key}}` in `content` with the matching
+ * value from `substitutions`. Keys are escaped for regex safety. Unrecognised
+ * placeholders are left intact — validation of the substitution map happens
+ * upstream in {@link computeAllowedKeys}.
+ *
+ * @param {string} content
+ * @param {Record<string, string>} substitutions
+ * @returns {string}
+ */
+export function applySubstitutions(content, substitutions) {
+  let out = content;
+  for (const [key, value] of Object.entries(substitutions)) {
+    out = out.replace(
+      new RegExp(`\\{\\{${escapeRegExp(key)}\\}\\}`, 'g'),
+      value,
+    );
+  }
+  return out;
+}
+
+/**
+ * Parse repeated `--substitution key=value` CLI pairs into a flat object.
+ * Throws {@link ValidationError} on malformed entries (missing `=` or empty key).
+ *
+ * @param {string[]} [pairs]
+ * @returns {Record<string, string>}
+ */
+export function parseSubstitutionPairs(pairs = []) {
+  const out = {};
+  for (const entry of pairs) {
+    const eq = entry.indexOf('=');
+    if (eq <= 0) {
+      throw new ValidationError(
+        `Invalid --substitution "${entry}"; expected key=value.`,
+        { entry },
+      );
+    }
+    const key = entry.slice(0, eq);
+    const value = entry.slice(eq + 1);
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Mutate `substitutions` in place to fold in CLI-derived defaults that should
+ * only override when the operator hasn't already supplied them via
+ * `--substitution`. Pulled out of `main` so the precedence rules can be
+ * unit-tested without the CLI layer.
+ *
+ * @param {Record<string, unknown>} values parsed CLI values
+ * @param {Record<string, string|undefined>} substitutions mutable map
+ */
+export function applyImplicitSubstitutions(values, substitutions) {
+  if (values.ticket && substitutions.ticketId === undefined) {
+    substitutions.ticketId = String(values.ticket);
+  }
+  if (values['base-branch'] && substitutions.baseBranch === undefined) {
+    substitutions.baseBranch = values['base-branch'];
+  }
+}
+
+/**
+ * Aggregate the allowed substitution key set for a run: built-ins plus
+ * per-audit declared keys across the requested auditWorkflows. Audits that
+ * are not registered in rules are ignored here — the runner rejects them with
+ * a findings entry before substitution matters.
+ *
+ * @param {{ audits?: Record<string, { substitutionKeys?: string[] }> }} rules
+ * @param {string[]} auditWorkflows
+ * @returns {Set<string>}
+ */
+export function computeAllowedKeys(rules, auditWorkflows) {
+  const allowed = new Set(BUILT_IN_SUBSTITUTION_KEYS);
+  for (const auditName of auditWorkflows) {
+    const entry = rules.audits?.[auditName];
+    if (!entry) continue;
+    for (const k of entry.substitutionKeys ?? []) {
+      allowed.add(k);
+    }
+  }
+  return allowed;
+}

package/.agents/scripts/lib/audit-suite/workflow-loader.js

@@ -0,0 +1,49 @@
+/**
+ * lib/audit-suite/workflow-loader.js — Filesystem IO for audit workflows.
+ *
+ * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
+ *
+ * The runner injects either {@link loadWorkflow} (production) or a stub (tests)
+ * via `injectedLoadWorkflow`. Same for {@link defaultWriteArtifact} and
+ * `injectedWriteArtifact`. Keeping the IO bound here lets the runner module
+ * stay free of `node:fs` imports and stay easy to unit-test.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Read an audit workflow markdown file. Returns `null` when the file is
+ * missing — the runner converts that into a `low`-severity finding rather
+ * than throwing, so a missing workflow doesn't fail the suite.
+ *
+ * @param {string} auditName
+ * @param {string} workflowsDir absolute path to the workflows root
+ * @returns {Promise<{ path: string, content: string } | null>}
+ */
+export async function loadWorkflow(auditName, workflowsDir) {
+  const workflowPath = path.join(workflowsDir, `${auditName}.md`);
+  try {
+    const content = await fs.readFile(workflowPath, 'utf8');
+    return { path: workflowPath, content };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Default artifact writer used when the caller passes a `--run-id` /
+ * `artifactPrefix`. Creates the artifacts dir on demand and returns the
+ * absolute path of the file written.
+ *
+ * @param {string} artifactsDir
+ * @param {string} fileName
+ * @param {string} content
+ * @returns {Promise<string>}
+ */
+export async function defaultWriteArtifact(artifactsDir, fileName, content) {
+  await fs.mkdir(artifactsDir, { recursive: true });
+  const fullPath = path.join(artifactsDir, fileName);
+  await fs.writeFile(fullPath, content, 'utf8');
+  return fullPath;
+}