wizz-method 2.0.0 → 2.1.1

package/tools/installer/core/yaml-cache.js

@@ -0,0 +1,105 @@
+// In-process (no disk) memoization for the YAML/CSV files the installer
+// parses repeatedly in a single run: skills-registry.yaml (up to 4x per
+// install), each module's module.yaml (up to 3x per module), and
+// skill-manifest.csv (up to 3x per platform). See audit 2026-09-11,
+// ACH-07/ACH-08/ACH-09: same file, same content, parsed several times with
+// several different ad-hoc try/catch blocks.
+//
+// This centralizes both the memoization and the error handling: "file
+// missing" always resolves to a normal value (null for YAML, [] for CSV)
+// instead of throwing, while "file exists but fails to parse" always throws
+// an Error whose message names the file path, so a bad manifest is
+// diagnosable instead of surfacing as a generic parser error.
+//
+// Cache key is the absolute path; each entry also stores the mtimeMs/size
+// seen at read time, mirroring the calculateFileHash cache in fs-native.js.
+// A file the installer itself rewrites mid-run (e.g. regenerating
+// manifest.yaml) is picked up fresh on the next read because its stat
+// changes; `invalidate(path)` is available for callers that want to force
+// that without waiting on stat granularity.
+
+const path = require('node:path');
+const yaml = require('yaml');
+const csvParseSync = require('csv-parse/sync');
+const fs = require('../fs-native');
+
+const yamlCache = new Map(); // absPath -> { mtimeMs, size, data }
+const csvCache = new Map(); // absPath -> { mtimeMs, size, data }
+
+/**
+ * Read + parse a file, memoized per absolute path until its mtime/size
+ * changes. Returns `whenMissing` (not a Promise) when the file doesn't
+ * exist. Throws an Error naming the path when it exists but `parse` throws.
+ * @param {string} filePath
+ * @param {Map} cache
+ * @param {(content: string) => *} parse
+ * @param {string} kind - Used in error messages ("YAML" | "CSV")
+ * @param {*} whenMissing
+ * @returns {Promise<*>}
+ */
+async function loadCachedFile(filePath, cache, parse, kind, whenMissing) {
+  const absPath = path.resolve(filePath);
+
+  if (!(await fs.pathExists(absPath))) {
+    cache.delete(absPath);
+    return whenMissing;
+  }
+
+  const stat = await fs.stat(absPath);
+  const cached = cache.get(absPath);
+  if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+    return cached.data;
+  }
+
+  const content = await fs.readFile(absPath, 'utf8');
+  let data;
+  try {
+    data = parse(content);
+  } catch (error) {
+    throw new Error(`Failed to parse ${kind} at ${absPath}: ${error.message}`);
+  }
+
+  cache.set(absPath, { mtimeMs: stat.mtimeMs, size: stat.size, data });
+  return data;
+}
+
+/**
+ * Parse a YAML file, memoized per absolute path for the life of the process.
+ * @param {string} filePath
+ * @returns {Promise<Object|null>} Parsed document, or null when absent
+ */
+async function loadYamlCached(filePath) {
+  return loadCachedFile(filePath, yamlCache, (content) => yaml.parse(content), 'YAML', null);
+}
+
+/**
+ * Parse a CSV file (columns:true, skip_empty_lines:true by default),
+ * memoized per absolute path for the life of the process.
+ * @param {string} filePath
+ * @param {Object} [csvOptions] - Overrides merged into the csv-parse options
+ * @returns {Promise<Array<Object>>} Parsed rows, or [] when absent
+ */
+async function loadCsvCached(filePath, csvOptions = {}) {
+  return loadCachedFile(
+    filePath,
+    csvCache,
+    (content) => csvParseSync.parse(content, { columns: true, skip_empty_lines: true, ...csvOptions }),
+    'CSV',
+    [],
+  );
+}
+
+/**
+ * Force the next loadYamlCached/loadCsvCached call for this path to reread
+ * from disk, regardless of what mtime/size it reports. Call this after the
+ * installer itself rewrites a file it may need to read again in the same
+ * process.
+ * @param {string} filePath
+ */
+function invalidate(filePath) {
+  const absPath = path.resolve(filePath);
+  yamlCache.delete(absPath);
+  csvCache.delete(absPath);
+}
+
+module.exports = { loadYamlCached, loadCsvCached, invalidate };

package/tools/installer/fs-native.js

@@ -4,6 +4,7 @@
 const fsp = require('node:fs/promises');
 const fs = require('node:fs');
 const path = require('node:path');
+const crypto = require('node:crypto');
 
 async function pathExists(p) {
   try {
@@ -22,6 +23,30 @@ async function remove(p) {
   await fsp.rm(p, { recursive: true, force: true });
 }
 
+// Concurrency cap for batched I/O (directory copy, file hashing): enough
+// parallelism to saturate typical disk I/O on a tree with hundreds/thousands
+// of small files, without opening an unbounded number of file descriptors
+// at once on very large trees.
+const DEFAULT_BATCH_SIZE = 32;
+
+// Runs `mapper` over `items` in concurrent batches of `batchSize`, returning
+// results in the same order as `items`. Each batch is awaited fully before
+// the next one starts, so the first rejection in a batch propagates and
+// stops further batches — same "first error wins" semantics as the
+// sequential loops this replaces, just with up to `batchSize` operations in
+// flight at once instead of one at a time.
+async function batchMap(items, mapper, batchSize = DEFAULT_BATCH_SIZE) {
+  const results = Array.from({ length: items.length });
+  for (let start = 0; start < items.length; start += batchSize) {
+    const batch = items.slice(start, start + batchSize);
+    const batchResults = await Promise.all(batch.map((item, i) => mapper(item, start + i)));
+    for (const [i, batchResult] of batchResults.entries()) {
+      results[start + i] = batchResult;
+    }
+  }
+  return results;
+}
+
 async function copy(src, dest, options = {}) {
   const filterFn = options.filter;
   const overwrite = options.overwrite !== false;
@@ -40,6 +65,16 @@ async function copy(src, dest, options = {}) {
       }
     }
     await fsp.copyFile(src, dest);
+    // Preserve the source mtime: node's copyFile doesn't, and the
+    // persistent hash cache (hash-cache.json, audit item 23) keys on
+    // size+mtime — a freshly stamped mtime would make every re-copied
+    // file look changed on the next update and invalidate the cache.
+    // Best-effort: mtime is an optimization, not a correctness contract.
+    try {
+      await fsp.utimes(dest, srcStat.atime, srcStat.mtime);
+    } catch {
+      // ignore — cache miss on the next run costs a hash, nothing more
+    }
     return;
   }
 
@@ -47,9 +82,7 @@ async function copy(src, dest, options = {}) {
     if (filterFn && !(await filterFn(src, dest))) return;
     await fsp.mkdir(dest, { recursive: true });
     const entries = await fsp.readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-      await copy(path.join(src, entry.name), path.join(dest, entry.name), options);
-    }
+    await batchMap(entries, (entry) => copy(path.join(src, entry.name), path.join(dest, entry.name), options));
   }
 }
 
@@ -70,22 +103,77 @@ function readJsonSync(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
+// Async sibling of readJsonSync. This used to exist as an fs-extra helper;
+// when fs-native replaced fs-extra (a6d075bd) it was dropped even though
+// custom-module-manager.js kept calling `fs.readJson(...)` — every one of
+// those calls threw TypeError, silently swallowed by surrounding
+// try/catch blocks, so cache-version checks there never actually read the
+// recorded metadata. Re-added (item 8c, auditoria 2026-09-11) because the
+// TAG@SHA early-return depends on reading .wizz-source.json.
+async function readJson(p) {
+  return JSON.parse(await fsp.readFile(p, 'utf8'));
+}
+
+// Central atomic-write primitive: write to a sibling `<dest>.tmp-<pid>-<rand>`
+// in the same directory (so the rename below is same-filesystem, never
+// `os.tmpdir()`) and `rename` it over the destination once the write
+// finishes — a reader never observes a partially written file. On any
+// failure the tmp file is removed (best-effort) and the error is rethrown;
+// the previous destination content, if any, is left untouched. Every write
+// through fs-native's `writeJson`/`writeFile` goes through this, so it's a
+// one-time fix for every config/manifest writer in the installer.
+async function writeFileAtomic(p, data, options) {
+  const tmpPath = `${p}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try {
+    await fsp.writeFile(tmpPath, data, options);
+    await fsp.rename(tmpPath, p);
+  } catch (error) {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
 async function writeJson(p, data, options = {}) {
   const spaces = options.spaces ?? 2;
-  await fsp.writeFile(p, JSON.stringify(data, null, spaces) + '\n', 'utf8');
+  await writeFileAtomic(p, JSON.stringify(data, null, spaces) + '\n', 'utf8');
+}
+
+// Single canonical SHA256-of-file-content implementation (previously
+// duplicated verbatim in core/manifest.js and core/manifest-generator.js,
+// with a third dead copy in file-ops.js). Memoized in-process by
+// `path:size:mtimeMs` — no disk cache — so the same unchanged file hashed
+// twice in one install/update run (e.g. once to detect user modifications,
+// once to write the new files-manifest.csv) only reads/hashes it once.
+// Returns `null` (never throws) when the file can't be read; callers that
+// need a different falsy sentinel adapt it locally.
+const fileHashCache = new Map();
+
+async function calculateFileHash(filePath) {
+  try {
+    const stat = await fsp.stat(filePath);
+    const cacheKey = `${filePath}:${stat.size}:${stat.mtimeMs}`;
+    if (fileHashCache.has(cacheKey)) {
+      return fileHashCache.get(cacheKey);
+    }
+    const content = await fsp.readFile(filePath);
+    const hash = crypto.createHash('sha256').update(content).digest('hex');
+    fileHashCache.set(cacheKey, hash);
+    return hash;
+  } catch {
+    return null;
+  }
 }
 
 module.exports = {
   // Native async (node:fs/promises)
   readFile: fsp.readFile,
-  writeFile: fsp.writeFile,
+  writeFile: writeFileAtomic,
   stat: fsp.stat,
   readdir: fsp.readdir,
   access: fsp.access,
   realpath: fsp.realpath,
   rename: fsp.rename,
   rmdir: fsp.rmdir,
-  unlink: fsp.unlink,
   chmod: fsp.chmod,
   mkdir: fsp.mkdir,
   mkdtemp: fsp.mkdtemp,
@@ -99,7 +187,10 @@ module.exports = {
   copy,
   move,
   readJsonSync,
+  readJson,
   writeJson,
+  calculateFileHash,
+  batchMap,
 
   // Sync methods from core node:fs
   existsSync: fs.existsSync.bind(fs),

package/tools/installer/ide/_config-driven.js

@@ -2,8 +2,9 @@ const path = require('node:path');
 const fs = require('../fs-native');
 const yaml = require('yaml');
 const prompts = require('../prompts');
-const csv = require('csv-parse/sync');
+const { loadCsvCached } = require('../core/yaml-cache');
 const { WIZZ_FOLDER_NAME } = require('./shared/path-utils');
+const { findExistingWizzDir } = require('../core/wizz-dir');
 const { getInstalledCanonicalIds, isWizzOwnedEntry } = require('./shared/installed-skills');
 
 // Reserved OpenCode slash commands. A skill whose canonicalId collides with
@@ -187,25 +188,6 @@ class ConfigDrivenIdeSetup {
    * @returns {Promise<Object>} Setup result
    */
   async setup(projectDir, wizzDir, options = {}) {
-    // Check for WIZZ files in ancestor directories that would cause duplicates
-    if (this.installerConfig?.ancestor_conflict_check) {
-      const conflict = await this.findAncestorConflict(projectDir);
-      if (conflict) {
-        await prompts.log.error(
-          `Found existing WIZZ skills in ancestor installation: ${conflict}\n` +
-            `  ${this.name} inherits skills from parent directories, so this would cause duplicates.\n` +
-            `  Please remove the WIZZ files from that directory first:\n` +
-            `    rm -rf "${conflict}"/wizz*`,
-        );
-        return {
-          success: false,
-          reason: 'ancestor-conflict',
-          error: `Ancestor conflict: ${conflict}`,
-          conflictDir: conflict,
-        };
-      }
-    }
-
     if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`);
 
     // Clean up any old WIZZ installation first
@@ -320,8 +302,7 @@ class ConfigDrivenIdeSetup {
     const targetDir = config.target_dir;
     const filter = config.commands_filter || null;
 
-    const csvContent = await fs.readFile(csvPath, 'utf8');
-    const records = csv.parse(csvContent, { columns: true, skip_empty_lines: true });
+    const records = await loadCsvCached(csvPath);
 
     for (const record of records) {
       const canonicalId = record.canonicalId;
@@ -428,11 +409,7 @@ class ConfigDrivenIdeSetup {
 
     if (!(await fs.pathExists(csvPath))) return 0;
 
-    const csvContent = await fs.readFile(csvPath, 'utf8');
-    const records = csv.parse(csvContent, {
-      columns: true,
-      skip_empty_lines: true,
-    });
+    const records = await loadCsvCached(csvPath);
 
     let count = 0;
 
@@ -651,13 +628,13 @@ class ConfigDrivenIdeSetup {
   }
 
   /**
-   * Find the _wizz directory in a project
+   * Find the _wizz directory in a project (delegated to core/wizz-dir.js, the
+   * single owner of `_wizz` resolution — item 20, auditoria 2026-09-11).
    * @param {string} projectDir - Project directory
    * @returns {string|null} Path to wizz dir or null
    */
   async _findWizzDir(projectDir) {
-    const wizzDir = path.join(projectDir, WIZZ_FOLDER_NAME);
-    return (await fs.pathExists(wizzDir)) ? wizzDir : null;
+    return findExistingWizzDir(projectDir);
   }
 
   /**
@@ -672,13 +649,10 @@ class ConfigDrivenIdeSetup {
     // Also add all currently installed skills from skill-manifest.csv
     const csvPath = path.join(wizzDir, '_config', 'skill-manifest.csv');
     try {
-      if (await fs.pathExists(csvPath)) {
-        const content = await fs.readFile(csvPath, 'utf8');
-        const records = csv.parse(content, { columns: true, skip_empty_lines: true });
-        for (const record of records) {
-          if (record.canonicalId) {
-            removals.add(record.canonicalId);
-          }
+      const records = await loadCsvCached(csvPath);
+      for (const record of records) {
+        if (record.canonicalId) {
+          removals.add(record.canonicalId);
         }
       }
     } catch {
@@ -857,10 +831,8 @@ class ConfigDrivenIdeSetup {
     const ids = new Set();
     if (!wizzDir) return ids;
     const csvPath = path.join(wizzDir, '_config', 'skill-manifest.csv');
-    if (!(await fs.pathExists(csvPath))) return ids;
     try {
-      const content = await fs.readFile(csvPath, 'utf8');
-      const records = csv.parse(content, { columns: true, skip_empty_lines: true });
+      const records = await loadCsvCached(csvPath);
       for (const record of records) {
         if (record.canonicalId) ids.add(record.canonicalId);
       }
@@ -1053,41 +1025,6 @@ class ConfigDrivenIdeSetup {
       }
     }
   }
-
-  /**
-   * Check ancestor directories for existing WIZZ files in the same target_dir.
-   * IDEs like Claude Code inherit commands from parent directories, so an existing
-   * installation in an ancestor would cause duplicate commands.
-   * @param {string} projectDir - Project directory being installed to
-   * @returns {Promise<string|null>} Path to conflicting directory, or null if clean
-   */
-  async findAncestorConflict(projectDir) {
-    const targetDir = this.installerConfig?.target_dir;
-    if (!targetDir) return null;
-
-    const resolvedProject = await fs.realpath(path.resolve(projectDir));
-    let current = path.dirname(resolvedProject);
-    const root = path.parse(current).root;
-
-    while (current !== root && current.length > root.length) {
-      const candidatePath = path.join(current, targetDir);
-      try {
-        if (await fs.pathExists(candidatePath)) {
-          const entries = await fs.readdir(candidatePath);
-          const ancestorWizzDir = await this._findWizzDir(current);
-          const canonicalIds = await getInstalledCanonicalIds(ancestorWizzDir);
-          if (entries.some((e) => isWizzOwnedEntry(e, canonicalIds))) {
-            return candidatePath;
-          }
-        }
-      } catch {
-        // Can't read directory — skip
-      }
-      current = path.dirname(current);
-    }
-
-    return null;
-  }
 }
 
 module.exports = { ConfigDrivenIdeSetup };

package/tools/installer/ide/platform-codes.js

@@ -6,6 +6,67 @@ const PLATFORM_CODES_PATH = path.join(__dirname, 'platform-codes.yaml');
 
 let _cachedPlatformCodes = null;
 
+/**
+ * Shallow-merge a platform's `installer` block onto the shared defaults.
+ * The entry's own keys win; any key whose merged value is `null` is dropped
+ * (this is how an entry declares "no global_target_dir at all", e.g. ona,
+ * replit, trae). Never mutates either input.
+ * @param {Object} [defaultInstaller] - `defaults.installer` from the YAML
+ * @param {Object} entryInstaller - the platform's own `installer` block
+ * @returns {Object} New merged installer object
+ */
+function mergeInstaller(defaultInstaller, entryInstaller) {
+  const merged = { ...defaultInstaller, ...entryInstaller };
+  const result = {};
+  for (const [key, value] of Object.entries(merged)) {
+    if (value !== null) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Apply `defaults` (preferred + installer.target_dir/global_target_dir) to
+ * one platform entry. A platform with no `installer:` block at all is
+ * returned untouched (defaults only apply to declared installer sections).
+ * @param {Object} defaults - top-level `defaults` from the YAML
+ * @param {Object} entry - one entry from `platforms`
+ * @returns {Object} New platform entry with defaults applied
+ */
+function applyDefaultsToEntry(defaults, entry) {
+  const { name, preferred, installer, ...rest } = entry;
+
+  // Rebuild in the pre-`defaults:` key order (name, preferred, installer,
+  // then anything else) so a plain object dump matches byte-for-byte.
+  const merged = { name };
+  merged.preferred = preferred === undefined ? defaults?.preferred : preferred;
+  if (installer) {
+    merged.installer = mergeInstaller(defaults?.installer, installer);
+  }
+  return { ...merged, ...rest };
+}
+
+/**
+ * Apply `defaults` across every entry in `platforms`, returning the config
+ * in the old shape (no top-level `defaults` key, consumers never read it).
+ * @param {Object} rawConfig - parsed platform-codes.yaml
+ * @returns {Object} New config object, same shape as before the `defaults:` block existed
+ */
+function applyDefaults(rawConfig) {
+  const { defaults, platforms, ...rest } = rawConfig || {};
+  if (!defaults) {
+    return rawConfig;
+  }
+
+  const mergedPlatforms = {};
+  for (const [code, entry] of Object.entries(platforms || {})) {
+    mergedPlatforms[code] = applyDefaultsToEntry(defaults, entry);
+  }
+
+  return { ...rest, platforms: mergedPlatforms };
+}
+
 /**
  * Load the platform codes configuration from YAML
  * @returns {Object} Platform codes configuration
@@ -20,7 +81,7 @@ async function loadPlatformCodes() {
   }
 
   const content = await fs.readFile(PLATFORM_CODES_PATH, 'utf8');
-  _cachedPlatformCodes = yaml.parse(content);
+  _cachedPlatformCodes = applyDefaults(yaml.parse(content));
   return _cachedPlatformCodes;
 }
 
@@ -31,26 +92,58 @@ function clearCache() {
   _cachedPlatformCodes = null;
 }
 
+/**
+ * The installable platforms, exactly as IdeManager exposes them: a platform is
+ * installable when it declares an `installer` section (IdeManager only builds
+ * handlers for those) and is not suspended (getAvailableIdes skips those).
+ * Same shape, same order — preferred first, then alphabetical by name.
+ *
+ * Kept here, in the leaf, so `formatPlatformList` does not have to reach back
+ * into `./manager` — that back-reference was the ide/manager ↔ ide/platform-codes
+ * require cycle (item 20, auditoria 2026-09-11). Test Suite 42 of
+ * test-installation-components.js asserts this list and the IDs `--tools`
+ * accepts stay in agreement.
+ * @param {Object} platformConfig - Parsed platform-codes.yaml
+ * @returns {Array<{id: string, name: string, targetDir: string, preferred: boolean}>}
+ */
+function listInstallablePlatforms(platformConfig) {
+  const entries = [];
+
+  for (const [platformCode, platformInfo] of Object.entries(platformConfig?.platforms || {})) {
+    // Skip if no installer config (platform may not need installation)
+    if (!platformInfo?.installer) continue;
+    // Skip suspended platforms (e.g., IDE doesn't support skills yet)
+    if (platformInfo.suspended) continue;
+
+    const name = platformInfo.name || platformCode;
+    // Filter out invalid entries (undefined name, empty key, etc.)
+    if (!platformCode || !name || typeof platformCode !== 'string' || typeof name !== 'string') continue;
+
+    entries.push({
+      id: platformCode,
+      name,
+      targetDir: platformInfo.installer.target_dir || '',
+      preferred: platformInfo.preferred || false,
+    });
+  }
+
+  // Sort: preferred first, then alphabetical
+  entries.sort((a, b) => {
+    if (a.preferred && !b.preferred) return -1;
+    if (!a.preferred && b.preferred) return 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  return entries;
+}
+
 /**
  * Format the installable platform list for human-readable output (used by --list-tools).
- * Sourced from IdeManager so this view matches what --tools accepts at install time
- * (suspended platforms excluded).
+ * Matches what --tools accepts at install time (suspended platforms excluded).
  * @returns {Promise<string>} Formatted multi-line string with id, name, target_dir, preferred flag.
  */
 async function formatPlatformList() {
-  const { IdeManager } = require('./manager');
-  const ideManager = new IdeManager();
-  await ideManager.ensureInitialized();
-
-  const entries = ideManager.getAvailableIdes().map((ide) => {
-    const handler = ideManager.handlers.get(ide.value);
-    return {
-      id: ide.value,
-      name: ide.name,
-      targetDir: handler?.installerConfig?.target_dir || '',
-      preferred: ide.preferred,
-    };
-  });
+  const entries = listInstallablePlatforms(await loadPlatformCodes());
 
   const idWidth = Math.max(...entries.map((e) => e.id.length), 'ID'.length);
   const nameWidth = Math.max(...entries.map((e) => e.name.length), 'Name'.length);
@@ -76,5 +169,7 @@ async function formatPlatformList() {
 module.exports = {
   loadPlatformCodes,
   clearCache,
+  applyDefaults,
+  listInstallablePlatforms,
   formatPlatformList,
 };