fraim 2.0.305 → 2.0.306

package/dist/src/cli/commands/sync.js

@@ -293,8 +293,11 @@ const runSync = async (options) => {
         });
         if (result.success) {
             // Local-dev sync bypasses Layer 1 (machine-level sync) below, but scripts
-            // still need to land in ~/.fraim/scripts/ or the reported count is a lie.
+            // and docs still need to land in ~/.fraim/ or the reported counts are a lie.
             await (0, remote_sync_1.syncScriptsToUserDir)(localRegistryFiles);
+            await (0, remote_sync_1.syncDocsToUserDir)(localRegistryFiles);
+            const { ensureUserLevelDependencies: ensureLocalUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+            ensureLocalUserLevelDependencies();
             console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
             const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
             removeLegacyVersionFromConfig(fraimDir);
@@ -354,6 +357,12 @@ const runSync = async (options) => {
     if (scriptsSynced > 0) {
         console.log(chalk_1.default.green(`  Synced ${scriptsSynced} scripts to ~/.fraim/scripts/`));
     }
+    // 1b2. Sync docs to ~/.fraim/docs/ (Issue #1508: machine-level docs, e.g.
+    // TROUBLESHOOTING.md, must exist on disk the same way scripts do)
+    const docsSynced = await (0, remote_sync_1.syncDocsToUserDir)(registryFiles);
+    if (docsSynced > 0) {
+        console.log(chalk_1.default.green(`  Synced ${docsSynced} docs to ~/.fraim/docs/`));
+    }
     // 1c. Refresh org home
     await refreshOrgCache(remoteUrl, apiKey);
     // 1d. Refresh manager home
@@ -361,9 +370,12 @@ const runSync = async (options) => {
     // 1e. Refresh MCP proxy launcher
     const { ensureFraimMcpLatestLauncher } = await Promise.resolve().then(() => __importStar(require('../mcp/fraim-mcp-latest-launcher')));
     ensureFraimMcpLatestLauncher();
-    // 1f. Ensure user-level directories
-    const { ensureUserLevelDirectories } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+    // 1f. Ensure user-level directories and runtime dependencies (Issue #1508:
+    // synced scripts like the DOCX review layer require npm deps such as
+    // adm-zip; a plain sync must install them, not just create directories)
+    const { ensureUserLevelDirectories, ensureUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
     ensureUserLevelDirectories();
+    ensureUserLevelDependencies();
     // 1g. Write sync metadata
     writeSyncMetadata('remote', remoteUrl);
     console.log(chalk_1.default.green('✅ Machine-level sync complete.'));

package/dist/src/cli/doctor/checks/scripts-checks.js

@@ -12,8 +12,73 @@ exports.getScriptsChecks = getScriptsChecks;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const module_1 = __importDefault(require("module"));
 const child_process_1 = require("child_process");
 const SCRIPTS_DIR = path_1.default.join(os_1.default.homedir(), '.fraim', 'scripts');
+// Conservative static-require extractor: only matches literal
+// require('name') / require("name") calls, not dynamic requires or imports.
+const STATIC_REQUIRE_PATTERN = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
+/**
+ * Recursively list .js/.cjs files under a directory.
+ */
+function listNodeScripts(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip vendored dependency trees. A script that ships its own bundled
+            // library (e.g. ~/.fraim/scripts/lib/node_modules/@scope/pkg/...) is
+            // not itself a FRAIM script requiring dependency resolution — it IS a
+            // resolved dependency. Recursing into it produces false-positive
+            // warnings about that library's own devDependency-only files (e.g. a
+            // benchmark/test file requiring a module never meant to be installed
+            // under ~/.fraim/node_modules). Confirmed against a real machine: see
+            // issue #1508 manual validation.
+            if (entry.name === 'node_modules')
+                continue;
+            results.push(...listNodeScripts(fullPath));
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.cjs'))) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Extract external (non-relative, non-absolute, non-builtin) module names
+ * statically required by a script, using its own directory for resolution.
+ */
+function extractExternalRequires(scriptPath) {
+    let content;
+    try {
+        content = fs_1.default.readFileSync(scriptPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const modules = new Set();
+    let match;
+    STATIC_REQUIRE_PATTERN.lastIndex = 0;
+    while ((match = STATIC_REQUIRE_PATTERN.exec(content)) !== null) {
+        const moduleName = match[1];
+        if (moduleName.startsWith('.') ||
+            moduleName.startsWith('/') ||
+            /^[a-zA-Z]:[\\/]/.test(moduleName) ||
+            moduleName.startsWith('node:') ||
+            module_1.default.builtinModules.includes(moduleName)) {
+            continue;
+        }
+        modules.add(moduleName);
+    }
+    return Array.from(modules);
+}
 /**
  * Check if scripts directory exists
  */
@@ -211,6 +276,73 @@ function checkPythonAvailability() {
         }
     };
 }
+/**
+ * Check that synced Node scripts can resolve their external runtime
+ * dependencies (e.g. `require('adm-zip')`) from their own directory.
+ *
+ * Distinguishes delivery (the script file exists) from executability (the
+ * script's require statements actually resolve). Issue #1508: `doctor`
+ * reported the DOCX review scripts healthy while all six threw
+ * `Cannot find module 'adm-zip'` at require time.
+ *
+ * Does not execute the scripts — only statically parses `require(...)`
+ * calls and resolves them the way Node would from the script's directory.
+ */
+function checkNodeScriptDependencies() {
+    return {
+        name: 'Node script dependencies available',
+        category: 'scripts',
+        critical: false,
+        run: async () => {
+            if (!fs_1.default.existsSync(SCRIPTS_DIR)) {
+                return {
+                    status: 'passed',
+                    message: 'No scripts synced — Node dependency check skipped'
+                };
+            }
+            const scripts = listNodeScripts(SCRIPTS_DIR);
+            if (scripts.length === 0) {
+                return {
+                    status: 'passed',
+                    message: 'No Node scripts synced — Node dependency check skipped'
+                };
+            }
+            const unresolved = {};
+            for (const scriptPath of scripts) {
+                const externalModules = extractExternalRequires(scriptPath);
+                const relativeScriptPath = path_1.default.relative(SCRIPTS_DIR, scriptPath);
+                for (const moduleName of externalModules) {
+                    try {
+                        require.resolve(moduleName, { paths: [path_1.default.dirname(scriptPath)] });
+                    }
+                    catch {
+                        if (!unresolved[moduleName])
+                            unresolved[moduleName] = [];
+                        unresolved[moduleName].push(relativeScriptPath);
+                    }
+                }
+            }
+            const unresolvedModules = Object.keys(unresolved);
+            if (unresolvedModules.length === 0) {
+                return {
+                    status: 'passed',
+                    message: `All Node script dependencies resolve (${scripts.length} scripts checked)`,
+                    details: { scriptCount: scripts.length }
+                };
+            }
+            const summary = unresolvedModules
+                .map((moduleName) => `${moduleName} (${unresolved[moduleName].join(', ')})`)
+                .join('; ');
+            return {
+                status: 'warning',
+                message: `Unresolved Node script dependencies: ${summary}`,
+                suggestion: 'Run fraim sync to install user-level runtime dependencies.',
+                command: 'fraim sync',
+                details: { unresolved }
+            };
+        }
+    };
+}
 /**
  * Get all scripts checks
  */
@@ -219,6 +351,7 @@ function getScriptsChecks() {
         checkScriptsDirectoryExists(),
         checkScriptsSynced(),
         checkScriptsExecutable(),
+        checkNodeScriptDependencies(),
         checkPythonAvailability()
     ];
 }

package/dist/src/cli/setup/user-level-sync.js

@@ -69,6 +69,7 @@ const script_sync_utils_1 = require("../utils/script-sync-utils");
  */
 const USER_LEVEL_RUNTIME_DEPS = {
     'node-edge-tts': '*', // used by scripts/author-audio.js
+    'adm-zip': '^0.6.0', // used by scripts/communication/*.js (DOCX review layer) — matches root/packages/* manifests
 };
 /**
  * Ensure the user-level FRAIM directory structure exists.

package/dist/src/cli/utils/remote-sync.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYNCED_CONTENT_BANNER_MARKER = void 0;
 exports.fetchRegistryFiles = fetchRegistryFiles;
 exports.syncScriptsToUserDir = syncScriptsToUserDir;
+exports.syncDocsToUserDir = syncDocsToUserDir;
 exports.syncFromRemote = syncFromRemote;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
@@ -188,32 +189,51 @@ async function fetchRegistryFiles(remoteUrl, apiKey) {
     return response.data.files || [];
 }
 /**
- * Sync script files to the user-level ~/.fraim/scripts/ directory.
- * Extracted from syncFromRemote so it can run without a project root.
+ * Sync a registry file subset (filtered by `type`) into a machine-level
+ * `~/.fraim/<subdir>/` directory: clean that directory, then write each
+ * matching file. Shared by syncScriptsToUserDir and syncDocsToUserDir so the
+ * clean-then-write and path-safety logic exists in exactly one place.
  */
-async function syncScriptsToUserDir(files) {
-    const scriptFiles = files.filter(f => f.type === 'script');
-    if (scriptFiles.length === 0)
+async function syncTypedFilesToUserDir(files, type, subdir, label) {
+    const matchingFiles = files.filter(f => f.type === type);
+    if (matchingFiles.length === 0)
         return 0;
     const userDir = (0, script_sync_utils_1.getUserFraimDir)();
-    const scriptsDir = (0, path_1.join)(userDir, 'scripts');
-    if (!(0, fs_1.existsSync)(scriptsDir)) {
-        (0, fs_1.mkdirSync)(scriptsDir, { recursive: true });
+    const targetDir = (0, path_1.join)(userDir, subdir);
+    if (!(0, fs_1.existsSync)(targetDir)) {
+        (0, fs_1.mkdirSync)(targetDir, { recursive: true });
     }
-    cleanDirectory(scriptsDir, (candidatePath) => {
-        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(scriptsDir)) {
-            assertPathInsideDirectory(scriptsDir, candidatePath, 'script directory');
+    cleanDirectory(targetDir, (candidatePath) => {
+        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(targetDir)) {
+            assertPathInsideDirectory(targetDir, candidatePath, `${label} directory`);
         }
     });
-    for (const file of scriptFiles) {
-        const { filePath } = resolveUserRegistryFile(scriptsDir, file.path, 'script file');
+    for (const file of matchingFiles) {
+        const { filePath } = resolveUserRegistryFile(targetDir, file.path, `${label} file`);
         const fileDir = (0, path_1.dirname)(filePath);
         if (!(0, fs_1.existsSync)(fileDir)) {
             (0, fs_1.mkdirSync)(fileDir, { recursive: true });
         }
         (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
     }
-    return scriptFiles.length;
+    return matchingFiles.length;
+}
+/**
+ * Sync script files to the user-level ~/.fraim/scripts/ directory.
+ * Extracted from syncFromRemote so it can run without a project root.
+ */
+async function syncScriptsToUserDir(files) {
+    return syncTypedFilesToUserDir(files, 'script', 'scripts', 'script');
+}
+/**
+ * Sync docs files to the user-level ~/.fraim/docs/ directory.
+ * Mirrors syncScriptsToUserDir so machine-level docs (e.g. TROUBLESHOOTING.md)
+ * are materialized on disk the same way machine-level scripts are.
+ * Issue #1508: agent guidance promises ~/.fraim/docs/TROUBLESHOOTING.md exists
+ * after sync, but only project-level fraim/docs/ was ever written.
+ */
+async function syncDocsToUserDir(files) {
+    return syncTypedFilesToUserDir(files, 'docs', 'docs', 'docs');
 }
 /**
  * Sync jobs and scripts from remote FRAIM server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.305",
+  "version": "2.0.306",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {