agileflow 3.4.2 → 4.0.0-alpha.1

package/src/runtime/ide/claude-code-skills.js

@@ -0,0 +1,202 @@
+/**
+ * Claude Code skill mirror.
+ *
+ * Plugin skills are sourced under `apps/cli/content/plugins/<id>/skills/<skill-id>/`
+ * and copied into `.agileflow/plugins/<id>/skills/<skill-id>/` by the
+ * sync engine. But Claude Code discovers skills from `.claude/skills/<skill-id>/`,
+ * so this module mirrors enabled plugin skills to that canonical
+ * location and prunes orphaned skills when plugins are disabled.
+ *
+ * We use copy (not symlink) for portability — Windows symlink behavior
+ * is inconsistent and Claude Code itself runs there. The duplication
+ * cost is negligible at v4-alpha skill counts.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
+ *
+ * @typedef {Object} MirrorResult
+ * @property {string[]} mirrored - skill ids written to .claude/skills/
+ * @property {string[]} pruned - skill ids removed from .claude/skills/ (orphans)
+ * @property {Array<{ skillId: string, error: string }>} skipped - skills whose source was missing
+ */
+
+/**
+ * Recursively copy a directory tree.
+ * @param {string} src
+ * @param {string} dest
+ */
+async function copyDir(src, dest) {
+  // Read the source listing FIRST. If src is missing (ENOENT), the
+  // error propagates BEFORE we create dest, so a missing source can't
+  // leave behind an empty destination dir for the caller to mistake
+  // for a successful copy.
+  const entries = await fs.promises.readdir(src, { withFileTypes: true });
+  await fs.promises.mkdir(dest, { recursive: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dest, e.name);
+    if (e.isDirectory()) {
+      await copyDir(s, d);
+    } else if (e.isFile()) {
+      await fs.promises.copyFile(s, d);
+    }
+  }
+}
+
+/**
+ * Recursively remove a directory tree (no-op when missing).
+ * @param {string} dir
+ */
+async function rmDir(dir) {
+  await fs.promises.rm(dir, { recursive: true, force: true });
+}
+
+/**
+ * Collect every skill declared by an enabled plugin manifest. Returns
+ * a list of `{ skillId, sourceDir }` where sourceDir is absolute.
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @returns {Array<{ skillId: string, sourceDir: string }>}
+ */
+function collectPluginSkills(orderedPlugins) {
+  /** @type {Array<{ skillId: string, sourceDir: string }>} */
+  const out = [];
+  for (const plugin of orderedPlugins) {
+    const skills =
+      plugin.provides && Array.isArray(plugin.provides.skills)
+        ? plugin.provides.skills
+        : [];
+    for (const s of skills) {
+      // Reject missing-or-empty id/dir. An empty `dir: ""` would
+      // pass `typeof === 'string'` but path.join silently treats it as
+      // the plugin root, which is never what the author intended.
+      if (
+        !s ||
+        typeof s.id !== 'string' ||
+        !s.id ||
+        typeof s.dir !== 'string' ||
+        !s.dir
+      ) {
+        continue;
+      }
+      out.push({
+        skillId: s.id,
+        sourceDir: path.join(plugin.dir, s.dir),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Mirror enabled plugin skills into `<projectRoot>/.claude/skills/<skill-id>/`
+ * and remove any `.claude/skills/<id>/` whose id is not in the current
+ * enabled set.
+ *
+ * Only AgileFlow-tracked skills are pruned: a skill is "tracked" iff
+ * its dir contains a `SKILL.md` whose first line is `---` AND its name
+ * appears in any plugin's `provides.skills` (i.e., we recognize it).
+ * To stay safe, we limit pruning to skills we've seen previously by
+ * recording the install set in the file index — but for v4-alpha
+ * simplicity, we prune every dir under `.claude/skills/` whose name
+ * matches an `agileflow-*` convention OR is in the previously-mirrored
+ * set on disk. Unknown user-placed skill dirs without that prefix are
+ * left alone.
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {string} projectRoot
+ * @returns {Promise<MirrorResult>}
+ */
+async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
+  const claudeSkills = path.join(projectRoot, '.claude', 'skills');
+  await fs.promises.mkdir(claudeSkills, { recursive: true });
+
+  const want = collectPluginSkills(orderedPlugins);
+  const wantIds = new Set(want.map((w) => w.skillId));
+
+  /** @type {string[]} */
+  const mirrored = [];
+  /** @type {Array<{ skillId: string, error: string }>} */
+  const skipped = [];
+  for (const { skillId, sourceDir } of want) {
+    const dest = path.join(claudeSkills, skillId);
+    try {
+      // Replace the destination wholesale so removed files in source
+      // don't linger in the user's .claude/skills/.
+      await rmDir(dest);
+      await copyDir(sourceDir, dest);
+      mirrored.push(skillId);
+    } catch (err) {
+      // A missing source dir (ENOENT) shouldn't crash the entire
+      // install — log and continue so other skills still mirror. A
+      // permission error or unrelated failure still propagates.
+      if (err && err.code === 'ENOENT') {
+        skipped.push({
+          skillId,
+          error: `source not found: ${sourceDir}`,
+        });
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  /** @type {string[]} */
+  const pruned = [];
+  let entries;
+  try {
+    entries = await fs.promises.readdir(claudeSkills, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return { mirrored, pruned };
+    throw err;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (wantIds.has(e.name)) continue;
+    // Only prune skills that LOOK like ours: agileflow-* prefix. This
+    // avoids blasting a user-placed third-party skill whose id we
+    // don't manage. A dedicated prune-from-index approach can replace
+    // this heuristic in a later phase.
+    if (!e.name.startsWith('agileflow-')) continue;
+    await rmDir(path.join(claudeSkills, e.name));
+    pruned.push(e.name);
+  }
+
+  return { mirrored, pruned, skipped };
+}
+
+/**
+ * Remove all AgileFlow-mirrored skills from `.claude/skills/`. Used
+ * when switching to a non-skill IDE.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>} ids that were removed
+ */
+async function unmirrorClaudeCodeSkills(projectRoot) {
+  const claudeSkills = path.join(projectRoot, '.claude', 'skills');
+  /** @type {string[]} */
+  const removed = [];
+  let entries;
+  try {
+    entries = await fs.promises.readdir(claudeSkills, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return removed;
+    throw err;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!e.name.startsWith('agileflow-')) continue;
+    await rmDir(path.join(claudeSkills, e.name));
+    removed.push(e.name);
+  }
+  return removed;
+}
+
+module.exports = {
+  mirrorClaudeCodeSkills,
+  unmirrorClaudeCodeSkills,
+  collectPluginSkills,
+};

package/src/runtime/installer/file-index.js

@@ -0,0 +1,112 @@
+/**
+ * File index read/write for the sync engine.
+ *
+ * The file index (`_cfg/files.json`) records the SHA256 hash of every
+ * file the installer has written into the user's project and whether
+ * the user has since diverged from that baseline. The sync engine uses
+ * the index to decide whether a destination file is safe to overwrite,
+ * should be preserved, or should trigger a stash.
+ *
+ * Schema (version 1):
+ *   {
+ *     schema: 1,
+ *     generated_at: <ISO string>,
+ *     version: <CLI version that wrote this index>,
+ *     files: {
+ *       "<posix-relative-path>": {
+ *         sha256: "<hex>",
+ *         protected: <bool>
+ *       },
+ *       ...
+ *     }
+ *   }
+ */
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {{ sha256: string, protected: boolean }} FileRecord
+ * @typedef {{ schema: 1, generated_at: string, version: string, files: Record<string, FileRecord> }} FileIndex
+ */
+
+/**
+ * Build an empty index. Caller fills `files` as sync proceeds.
+ * @param {string} cliVersion
+ * @returns {FileIndex}
+ */
+function emptyIndex(cliVersion) {
+  return {
+    schema: SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    version: cliVersion,
+    files: {},
+  };
+}
+
+/**
+ * Read an index file. Returns null on missing file, malformed JSON, or
+ * schema mismatch — the caller should treat any of those as "first
+ * install / no baseline" and start fresh.
+ *
+ * @param {string} indexPath
+ * @returns {Promise<FileIndex|null>}
+ */
+async function readFileIndex(indexPath) {
+  let raw;
+  try {
+    raw = await fs.promises.readFile(indexPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (parsed.schema !== SCHEMA_VERSION) return null;
+  if (!parsed.files || typeof parsed.files !== 'object' || Array.isArray(parsed.files)) {
+    return null;
+  }
+  return /** @type {FileIndex} */ (parsed);
+}
+
+/**
+ * Write the index atomically (temp + rename), matching the writer's
+ * pattern for the user config. Callers should pass the final index they
+ * produced — nothing about `files` is validated here.
+ *
+ * @param {string} indexPath
+ * @param {FileIndex} index
+ * @returns {Promise<void>}
+ */
+async function writeFileIndex(indexPath, index) {
+  const dir = path.dirname(indexPath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const tmp = path.join(
+    dir,
+    `${path.basename(indexPath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  const payload = {
+    ...index,
+    generated_at: new Date().toISOString(),
+  };
+  const content = JSON.stringify(payload, null, 2) + '\n';
+  try {
+    await fs.promises.writeFile(tmp, content, 'utf8');
+    await fs.promises.rename(tmp, indexPath);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+}
+
+module.exports = { SCHEMA_VERSION, emptyIndex, readFileIndex, writeFileIndex };

package/src/runtime/installer/install.js

@@ -0,0 +1,306 @@
+/**
+ * `installPlugins` — end-to-end orchestrator that wires the plugin
+ * registry, validator, resolver, and sync engine into a single call.
+ *
+ * Flow:
+ *   1. Strict-validate every discovered plugin (errors → throw with
+ *      a flat report; warnings ignored here, surfaced by `doctor`).
+ *   2. Resolve transitive dependencies + topological order from the
+ *      user's selection (resolver throws on cycles or missing deps).
+ *   3. Read the existing `_cfg/files.json` (or build a fresh index).
+ *   4. For each resolved plugin, walk its source directory and
+ *      `syncFile` every file into `<agileflowDir>/plugins/<id>/...`.
+ *   5. Remove directories of previously-installed plugins that are no
+ *      longer enabled. Their entries are also pruned from the file
+ *      index.
+ *   6. Write the file index atomically.
+ *
+ * Side effects only on the destination project. The bundled `content/`
+ * source tree is read-only.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const { syncFile, emptyCounters } = require('./sync-engine.js');
+const {
+  emptyIndex,
+  readFileIndex,
+  writeFileIndex,
+} = require('./file-index.js');
+const { resolvePlugins } = require('../plugins/resolver.js');
+const {
+  validatePluginSet,
+  hasErrors,
+} = require('../plugins/validator.js');
+const {
+  writeAggregatedManifest,
+  removeAggregatedManifest,
+  buildHookManifest,
+} = require('../hooks/aggregator.js');
+const { normalizeManifest } = require('../hooks/manifest-loader.js');
+const { capabilitiesFor } = require('../ide/capabilities.js');
+const {
+  writeClaudeCodeSettings,
+  removeClaudeCodeSettings,
+} = require('../ide/claude-code-settings.js');
+const {
+  mirrorClaudeCodeSkills,
+  unmirrorClaudeCodeSkills,
+} = require('../ide/claude-code-skills.js');
+
+/**
+ * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
+ *
+ * @typedef {Object} InstallOptions
+ * @property {PluginManifest[]} discovered
+ * @property {Iterable<string>} userSelected
+ * @property {string} agileflowDir - target install root (typically `<cwd>/.agileflow`)
+ * @property {string} cliVersion - written into the file index header
+ * @property {string} [ide='claude-code'] - target IDE for capability gating
+ * @property {boolean} [force=false] - overwrite user modifications
+ *
+ * @typedef {Object} InstallResult
+ * @property {string[]} ordered - plugin ids in install order
+ * @property {string[]} autoEnabled - ids pulled in via depends
+ * @property {string[]} removed - ids whose dir was removed (no longer enabled)
+ * @property {import('./sync-engine.js').FileOpsCounters} ops
+ * @property {string} agileflowDir
+ * @property {string} indexPath
+ * @property {string} timestamp
+ * @property {string|null} hookManifestPath - path of the written hook manifest, or null
+ * @property {string|null} settingsPath - path of the written .claude/settings.json, or null
+ * @property {string[]} skillsMirrored - skill ids copied into .claude/skills/
+ * @property {string[]} skillsPruned - skill ids removed from .claude/skills/
+ * @property {Array<{skillId:string, error:string}>} [skillsSkipped] - skills with missing source
+ * @property {string} ide - the target IDE for this install
+ */
+
+/**
+ * Build a stable file-system-safe timestamp string for stash bucketing.
+ * @returns {string}
+ */
+function makeTimestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+/** @param {string} p */
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+/**
+ * Yield absolute paths to every file under `dir`, depth-first.
+ * @param {string} dir
+ * @returns {AsyncGenerator<string>}
+ */
+async function* walkFiles(dir) {
+  const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (e.isFile()) {
+      yield full;
+    }
+  }
+}
+
+/**
+ * Sync every file in `plugin.dir` into `agileflowDir/plugins/<id>/...`.
+ *
+ * @param {PluginManifest} plugin
+ * @param {string} agileflowDir
+ * @param {import('./file-index.js').FileIndex} fileIndex
+ * @param {import('./sync-engine.js').FileOpsCounters} ops
+ * @param {string} timestamp
+ * @param {boolean} force
+ */
+async function installOnePlugin(plugin, agileflowDir, fileIndex, ops, timestamp, force) {
+  const cfgDir = path.join(agileflowDir, '_cfg');
+  const pluginRoot = path.join(agileflowDir, 'plugins', plugin.id);
+
+  for await (const sourcePath of walkFiles(plugin.dir)) {
+    const relInPlugin = path.relative(plugin.dir, sourcePath);
+    const dest = path.join(pluginRoot, relInPlugin);
+    const relativePath = toPosix(path.relative(agileflowDir, dest));
+    const content = await fs.promises.readFile(sourcePath);
+    await syncFile({
+      content,
+      dest,
+      relativePath,
+      fileIndex,
+      cfgDir,
+      timestamp,
+      force,
+      ops,
+    });
+  }
+}
+
+/**
+ * Remove plugin directories for plugins that were previously installed
+ * (have entries in the file index under `plugins/<id>/...`) but are
+ * NOT in the currently enabled set. Their file index entries are also
+ * pruned so a future re-enable produces fresh CREATED records.
+ *
+ * @param {Set<string>} enabledIds
+ * @param {Set<string>} knownIds - all discovered ids (so we don't blow
+ *   away unknown directories the user might have placed manually)
+ * @param {string} agileflowDir
+ * @param {import('./file-index.js').FileIndex} fileIndex
+ * @param {import('./sync-engine.js').FileOpsCounters} ops
+ * @returns {Promise<string[]>} the plugin ids that were removed
+ */
+async function removeDisabledPlugins(enabledIds, knownIds, agileflowDir, fileIndex, ops) {
+  const pluginsRoot = path.join(agileflowDir, 'plugins');
+  /** @type {string[]} */
+  const removed = [];
+  let entries;
+  try {
+    entries = await fs.promises.readdir(pluginsRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return removed;
+    throw err;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const id = e.name;
+    if (enabledIds.has(id)) continue;
+    if (!knownIds.has(id)) continue; // leave unknown dirs alone
+    const dir = path.join(pluginsRoot, id);
+    await fs.promises.rm(dir, { recursive: true, force: true });
+    for (const key of Object.keys(fileIndex.files)) {
+      if (key.startsWith(`plugins/${id}/`)) {
+        delete fileIndex.files[key];
+      }
+    }
+    removed.push(id);
+    ops.removed++;
+  }
+  return removed;
+}
+
+/**
+ * @param {InstallOptions} options
+ * @returns {Promise<InstallResult>}
+ */
+async function installPlugins(options) {
+  const {
+    discovered,
+    userSelected,
+    agileflowDir,
+    cliVersion,
+    ide = 'claude-code',
+    force = false,
+  } = options;
+
+  // 1. Strict-validate. Errors abort; warnings are surfaced elsewhere.
+  const issues = validatePluginSet(discovered);
+  if (hasErrors(issues)) {
+    const errors = issues
+      .filter((i) => i.severity === 'error')
+      .map((i) => `  ${i.pluginId}: ${i.message}`)
+      .join('\n');
+    throw new Error(`Plugin validation failed:\n${errors}`);
+  }
+
+  // 2. Resolve dependency order.
+  const { ordered, autoEnabled } = resolvePlugins(discovered, userSelected);
+
+  // 3. Read or seed the file index.
+  const cfgDir = path.join(agileflowDir, '_cfg');
+  const indexPath = path.join(cfgDir, 'files.json');
+  const fileIndex = (await readFileIndex(indexPath)) || emptyIndex(cliVersion);
+
+  // 4-6 wrapped in try/finally so the file index is ALWAYS persisted,
+  // even if a sync fails mid-loop. Otherwise on-disk files would exist
+  // without index entries and the next run would misclassify them as
+  // "user-modified" and stash them.
+  const ops = emptyCounters();
+  const timestamp = makeTimestamp();
+  /** @type {string[]} */
+  let removed = [];
+
+  try {
+    // 4. Sync each plugin in order.
+    for (const plugin of ordered) {
+      await installOnePlugin(plugin, agileflowDir, fileIndex, ops, timestamp, force);
+    }
+
+    // 5. Remove disabled plugin directories.
+    const enabledIds = new Set(ordered.map((p) => p.id));
+    const knownIds = new Set(discovered.map((p) => p.id));
+    removed = await removeDisabledPlugins(
+      enabledIds,
+      knownIds,
+      agileflowDir,
+      fileIndex,
+      ops,
+    );
+  } finally {
+    // 6. Persist the file index. Always.
+    await writeFileIndex(indexPath, fileIndex);
+  }
+
+  // 7. Validate-before-write: build the manifest in memory and run
+  //    the loader's normalizer against it. Surfacing an invalid plugin
+  //    contribution NOW prevents step 8 from registering hook
+  //    dispatchers in settings.json that point at an unparseable
+  //    manifest.
+  const caps = capabilitiesFor(ide);
+  let hookManifestPath = null;
+  if (caps.hooks) {
+    const manifestObj = buildHookManifest(ordered);
+    try {
+      normalizeManifest(manifestObj);
+    } catch (err) {
+      throw new Error(`Hook manifest validation failed: ${err.message}`);
+    }
+    hookManifestPath = await writeAggregatedManifest(ordered, agileflowDir);
+  } else {
+    await removeAggregatedManifest(agileflowDir);
+  }
+
+  // 8. Register or unregister our hook dispatchers in
+  //    `.claude/settings.json`. Only when ide=claude-code.
+  const projectRoot = path.dirname(agileflowDir);
+  let settingsPath = null;
+  if (ide === 'claude-code') {
+    settingsPath = await writeClaudeCodeSettings(projectRoot);
+  } else {
+    await removeClaudeCodeSettings(projectRoot);
+  }
+
+  // 9. Mirror skills into `.claude/skills/<id>/`. Copy (not symlink)
+  //    for Windows portability. Missing skill sources are skipped
+  //    gracefully; non-ENOENT errors propagate.
+  let skillsMirrored = [];
+  let skillsPruned = [];
+  let skillsSkipped = [];
+  if (caps.skills) {
+    const r = await mirrorClaudeCodeSkills(ordered, projectRoot);
+    skillsMirrored = r.mirrored;
+    skillsPruned = r.pruned;
+    skillsSkipped = r.skipped || [];
+  } else {
+    skillsPruned = await unmirrorClaudeCodeSkills(projectRoot);
+  }
+
+  return {
+    ordered: ordered.map((p) => p.id),
+    autoEnabled,
+    removed,
+    ops,
+    agileflowDir,
+    indexPath,
+    timestamp,
+    hookManifestPath,
+    settingsPath,
+    skillsMirrored,
+    skillsPruned,
+    skillsSkipped,
+    ide,
+  };
+}
+
+module.exports = { installPlugins };

package/src/runtime/installer/stash.js

@@ -0,0 +1,61 @@
+/**
+ * Stash writer for the sync engine.
+ *
+ * When the sync engine encounters a user-modified destination file whose
+ * content diverges from the incoming upstream version, it preserves the
+ * user's file in place and writes the new version to a stash directory
+ * at `<cfgDir>/updates/<timestamp>/<relativePath>` so the user can
+ * manually diff and merge.
+ *
+ * Path-traversal-safe: a malicious or buggy `relativePath` containing
+ * `..` segments cannot escape the updates directory. The resolved
+ * destination is checked against the resolved updates root and rejected
+ * if it points outside.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @param {Object} args
+ * @param {string} args.cfgDir - absolute path to .agileflow/_cfg/
+ * @param {string} args.timestamp - stable stamp for this sync run
+ * @param {string} args.relativePath - posix-style path (no leading slash, no `..`)
+ * @param {Buffer|string} args.content - bytes to stash (as would have been written)
+ * @returns {Promise<string>} absolute path the stash file was written to
+ */
+async function writeStash({ cfgDir, timestamp, relativePath, content }) {
+  // Reject absolute paths up front. `path.join` would otherwise treat
+  // `/etc/passwd` as a relative segment, silently producing
+  // `<updatesRoot>/etc/passwd` which is technically inside the root
+  // but not what the caller intended.
+  if (path.isAbsolute(relativePath)) {
+    throw new Error(
+      `writeStash: relativePath "${relativePath}" escapes the updates directory (must be a relative path)`,
+    );
+  }
+
+  const updatesRoot = path.resolve(path.join(cfgDir, 'updates', timestamp));
+  const stashPath = path.resolve(path.join(updatesRoot, relativePath));
+
+  // Path-traversal guard: stashPath must be at or under updatesRoot.
+  // We check both equality (a relativePath that resolves to the dir
+  // itself) and the path.sep prefix (any descendant).
+  if (
+    stashPath !== updatesRoot &&
+    !stashPath.startsWith(updatesRoot + path.sep)
+  ) {
+    throw new Error(
+      `writeStash: relativePath "${relativePath}" escapes the updates directory`,
+    );
+  }
+
+  await fs.promises.mkdir(path.dirname(stashPath), { recursive: true });
+  if (typeof content === 'string') {
+    await fs.promises.writeFile(stashPath, content, 'utf8');
+  } else {
+    await fs.promises.writeFile(stashPath, content);
+  }
+  return stashPath;
+}
+
+module.exports = { writeStash };