@ldgerrits/rogen 1.4.1 → 1.4.3

package/README.md

@@ -5,20 +5,22 @@
 </div>
 
 <div align="center">
-    <a href="https://rogen-playfully.vercel.app"><strong>Documentation</strong></a>
+    <a href="https://rogen-playfully.vercel.app"><strong>documentation</strong></a>
 </div>
 
 ---
 
-A CLI tool enabling feature-based architecture through automated routing of client, server, and shared code to Roblox services.
+<div align="center">
+    A CLI tool that enables feature-based architecture for Roblox
+</div>
 
 ## Features
 
-- **Feature Folders:** Store related client, server and shared scripts inside a single folder.
-- **Auto-Routing:** Route files to Roblox services automatically using Rojo or Argon.
+- **Feature Folders:** Keep related client, server, and shared code inside a single folder.
+- **Auto-Routing:** Map files to Roblox services automatically using Rojo or Argon.
 - **Multi-Place Support:** Merge multiple source directories to share core systems across different places.
-- **Environment Tags:** Filter test files and inject mock files at build time using tags.
-- **Custom Pathing:** Control the final output structure using invisible folders and marker files.
+- **Environment Tags:** Filter test files and inject mock dependencies at build time using tags.
+- **Granular Control:** Shape the project tree using invisible folders, hoisting, and marker files.
 - **Modern Tooling:** Support Luau, roblox-ts, and Darklua pipelines out of the box.
 
 ## Contributing

package/dist/build.js

@@ -3,7 +3,7 @@ import path from "path";
 import picomatch from "picomatch";
 import { applyCasing, getOrCreateNode, pruneObject, sortObject, findMissingPaths, toPosix, collapseFolders, isInitFile, isValidSource, findExposedDataFiles, } from "./tree.js";
 import { resolveRoute, } from "./route.js";
-import { serviceParents, generateRoutingMaps, defaultConfig, } from "./constants.js";
+import { serviceParents, generateRoutingMaps, defaultConfig, services, } from "./constants.js";
 const SYSTEM_MARKERS = {
     structure: true,
     verbatim: true,
@@ -116,6 +116,25 @@ export async function build(targetConfig, baseProjectTree, config, env, sourcePa
         modeCopy.build = cliArgs.build;
     }
     const rojoTree = structuredClone(baseProjectTree);
+    // Pre-populate all routing containers to prevent desync issues
+    for (const targetService of Object.values(services)) {
+        let current = rojoTree.tree;
+        if (serviceParents[targetService]) {
+            current = getOrCreateNode(current, serviceParents[targetService]);
+        }
+        getOrCreateNode(current, targetService);
+    }
+    if (config.aliases) {
+        for (const aliasPath of Object.values(config.aliases)) {
+            if (typeof aliasPath === "string") {
+                const parts = aliasPath.split(".");
+                let current = rojoTree.tree;
+                for (const part of parts) {
+                    current = getOrCreateNode(current, part);
+                }
+            }
+        }
+    }
     const mergedTags = { ...(config.tags || {}), ...(modeCopy.tags || {}) };
     const knownTags = new Set(Object.keys(config.tags || {}).map((t) => t.toLowerCase()));
     const activeTags = new Set(Object.keys(mergedTags)
@@ -146,6 +165,7 @@ export async function build(targetConfig, baseProjectTree, config, env, sourcePa
         tagRegexes,
     };
     const combinedGlobIgnorePaths = Array.from(new Set([
+        ...(rojoTree.globIgnorePaths || []),
         ...(config.globIgnorePaths || []),
         ...(modeCopy.globIgnorePaths || []),
     ]));
@@ -167,10 +187,8 @@ export async function build(targetConfig, baseProjectTree, config, env, sourcePa
         };
         walkSource(sourcePath, sourcePath, listings, (filepath, isInit, isSync) => {
             const relativePath = path.relative(sourcePath, filepath);
-            if (relativePath && isIgnored(toPosix(relativePath)))
-                return;
             const { targetService, wrapperFolder, virtualParts, nodeName, projectPath, dropped, unwrap, } = resolveRoute(relativePath, isInit, newContext, isSync);
-            if (dropped)
+            if (dropped || (projectPath && isIgnored(toPosix(projectPath))))
                 return;
             fileCount++;
             let current = rojoTree.tree;
@@ -194,10 +212,13 @@ export async function build(targetConfig, baseProjectTree, config, env, sourcePa
             const existingNode = existingNodeRaw || {};
             const newNode = {
                 ...existingNode,
-                $path: projectPath,
+                $path: { optional: projectPath },
             };
             if (newNode.$className === "Folder") {
                 delete newNode.$className;
+                if (newNode.$ignoreUnknownInstances === false) {
+                    delete newNode.$ignoreUnknownInstances;
+                }
             }
             current[nodeName] = newNode;
             nodeOrigins.set(newNode, {
@@ -209,8 +230,11 @@ export async function build(targetConfig, baseProjectTree, config, env, sourcePa
     const outputDir = path.dirname(modeCopy.output);
     const removed = [];
     const prunedTree = pruneObject(rojoTree.tree, context.build, outputDir, removed);
-    collapseFolders(prunedTree, context.build, outputDir);
+    collapseFolders(prunedTree, context.build, outputDir, isIgnored);
     rojoTree.tree = prunedTree;
+    if (combinedGlobIgnorePaths.length > 0) {
+        rojoTree.globIgnorePaths = combinedGlobIgnorePaths;
+    }
     const sortedTree = sortObject(rojoTree);
     const missingPaths = findMissingPaths(sortedTree.tree, context.build, outputDir);
     const exposedDataFiles = findExposedDataFiles(sortedTree.tree);

package/dist/bundle.cjs

@@ -8858,14 +8858,15 @@ var import_chokidar = __toESM(require_chokidar(), 1);
 var import_util = require("util");
 function printHelp(logger) {
   const helpText = `
-Rogen - Feature-based folder routing for Roblox
+Rogen - Feature-based architecture for Roblox
 
 Usage:
   rogen [command] [options]
 
 Commands:
   init                 Generate a .rogen.json config file
-  watch                Watch the source and generate automatically
+  build                Build the project
+  watch                Watch the source and build automatically
 
 Options:
   -c, --config <path>  Specify custom config file
@@ -8916,6 +8917,7 @@ function parseCliArgs(args = process.argv.slice(2), logger) {
         parsedArgs.help = true;
       } else if (subcommand === "version") {
         parsedArgs.version = true;
+      } else if (subcommand === "build") {
       } else {
         const errorMsg = `unknown subcommand "${positionals[0]}".
 Run 'rogen --help' to see a list of available commands.`;
@@ -8964,7 +8966,17 @@ var import_fs = __toESM(require("fs"), 1);
 var import_path = __toESM(require("path"), 1);
 
 // src/constants.ts
-var version = "1.4.1";
+var version = "1.4.3";
+var dataExtensions = /* @__PURE__ */ new Set([
+  ".csv",
+  ".txt",
+  ".json",
+  ".toml",
+  ".yaml",
+  ".yml",
+  ".msgpack",
+  ".md"
+]);
 var defaultProject = {
   name: "roblox-game",
   tree: { $className: "DataModel" }
@@ -9018,6 +9030,10 @@ var serviceParents = {
   StarterPlayerScripts: "StarterPlayer",
   StarterCharacterScripts: "StarterPlayer"
 };
+var combinedServices = /* @__PURE__ */ new Set([
+  ...Object.values(services),
+  ...Object.values(serviceParents)
+]);
 var serverContainers = /* @__PURE__ */ new Set([
   "ServerScriptService",
   "ServerStorage"
@@ -9418,9 +9434,27 @@ function applyCasing(value, casing) {
   const firstCharacter = casing === "PascalCase" ? value[0].toUpperCase() : value[0].toLowerCase();
   return firstCharacter + value.slice(1);
 }
+function getPathString(node) {
+  const p = node.$path;
+  if (typeof p === "string") return p;
+  if (p && typeof p === "object" && typeof p.optional === "string")
+    return p.optional;
+  return void 0;
+}
 function getOrCreateNode(parent, key, className) {
+  const isRootService = combinedServices.has(key) || className && combinedServices.has(className);
   if (!parent[key]) {
-    parent[key] = className == null ? {} : { $className: className };
+    parent[key] = className == null ? {} : {
+      $className: className,
+      ...isRootService ? {} : { $ignoreUnknownInstances: false }
+    };
+  } else if (className != null) {
+    const existing = parent[key];
+    if (existing.$ignoreUnknownInstances === void 0 && existing.$path === void 0) {
+      if (!isRootService) {
+        existing.$ignoreUnknownInstances = false;
+      }
+    }
   }
   return parent[key];
 }
@@ -9430,16 +9464,20 @@ function pruneObject(node, buildDir, outputDir, removed = [], treePath = "") {
     if (typeof val !== "object" || val === null) continue;
     const childTreePath = treePath ? `${treePath}.${key}` : key;
     const childNode = val;
-    if (childNode.$path) {
-      if (hasPathPrefix(childNode.$path, buildDir)) continue;
-      const absolutePath = import_path2.default.resolve(outputDir, childNode.$path);
-      if (!import_fs2.default.existsSync(absolutePath)) {
-        delete node[key];
-        removed.push({
-          treePath: childTreePath,
-          rojoPath: childNode.$path
-        });
-        continue;
+    const childPath = getPathString(childNode);
+    if (childPath) {
+      if (hasPathPrefix(childPath, buildDir)) continue;
+      const isOptional = typeof childNode.$path === "object";
+      if (!isOptional) {
+        const absolutePath = import_path2.default.resolve(outputDir, childPath);
+        if (!import_fs2.default.existsSync(absolutePath)) {
+          delete node[key];
+          removed.push({
+            treePath: childTreePath,
+            rojoPath: childPath
+          });
+          continue;
+        }
       }
     }
     pruneObject(childNode, buildDir, outputDir, removed, childTreePath);
@@ -9462,14 +9500,15 @@ function findMissingPaths(node, buildDir, outputDir, missing = [], treePath = ""
     if (typeof val !== "object" || val === null) continue;
     const childTreePath = treePath ? `${treePath}.${key}` : key;
     const childNode = val;
-    if (childNode.$path && hasPathPrefix(childNode.$path, buildDir)) {
-      const absolutePath = import_path2.default.resolve(outputDir, childNode.$path);
+    const childPath = getPathString(childNode);
+    if (childPath && hasPathPrefix(childPath, buildDir)) {
+      const absolutePath = import_path2.default.resolve(outputDir, childPath);
       if (!import_fs2.default.existsSync(absolutePath)) {
         missing.push({
           parent: node,
           key,
           treePath: childTreePath,
-          path: childNode.$path,
+          path: childPath,
           absolutePath
         });
       }
@@ -9488,8 +9527,10 @@ var isScript = (filename) => /\.(tsx?|luau|lua)$/i.test(filename) && !filename.t
 var isModel = (filename) => /\.(rbxm|rbxmx)$/i.test(filename);
 function isData(filename) {
   if (isScript(filename) || isModel(filename)) return false;
+  if (filename.toLowerCase().endsWith(".d.ts")) return false;
   if (filename.startsWith(".")) return false;
-  return /\.[a-z0-9]+$/i.test(filename);
+  const ext = import_path2.default.extname(filename).toLowerCase();
+  return dataExtensions.has(ext);
 }
 var isValidSource = (filename) => isScript(filename) || isModel(filename) || isData(filename);
 var isInitFile = (filename) => isScript(filename) && /^(index|init)([.-][a-z0-9_]+)?\./i.test(filename);
@@ -9505,7 +9546,7 @@ function getRojoBaseName(filename) {
   }
   return filename;
 }
-function collapseFolders(node, buildDir, outputDir) {
+function collapseFolders(node, buildDir, outputDir, isIgnored = () => false) {
   let childCount = 0;
   let canCollapse = node.$path === void 0;
   let commonDir = null;
@@ -9514,12 +9555,13 @@ function collapseFolders(node, buildDir, outputDir) {
     const val = node[key];
     if (typeof val !== "object" || val === null) continue;
     const childNode = val;
-    collapseFolders(childNode, buildDir, outputDir);
+    collapseFolders(childNode, buildDir, outputDir, isIgnored);
     childCount++;
-    if (!childNode.$path) {
+    const childPath = getPathString(childNode);
+    if (!childPath) {
       canCollapse = false;
     } else {
-      const childAbsPath = import_path2.default.resolve(outputDir, childNode.$path);
+      const childAbsPath = import_path2.default.resolve(outputDir, childPath);
       const parentDir = import_path2.default.dirname(childAbsPath);
       if (commonDir === null) {
         commonDir = parentDir;
@@ -9539,10 +9581,11 @@ function collapseFolders(node, buildDir, outputDir) {
   if (!hasPathPrefix(toPosix(commonDir), toPosix(absoluteBuildDir))) {
     return;
   }
+  const relativeCommonDir = toPosix(import_path2.default.relative(outputDir, commonDir));
   try {
     const diskItems = import_fs2.default.readdirSync(commonDir);
     const visibleDiskItems = diskItems.filter(
-      (item) => !item.startsWith(".")
+      (item) => !item.startsWith(".") && !isIgnored(toPosix(import_path2.default.join(relativeCommonDir, item)))
     );
     if (visibleDiskItems.length !== childCount) {
       return;
@@ -9550,13 +9593,12 @@ function collapseFolders(node, buildDir, outputDir) {
   } catch {
     return;
   }
-  const relativeCommonDir = toPosix(import_path2.default.relative(outputDir, commonDir));
   for (const key in node) {
     if (!key.startsWith("$")) {
       delete node[key];
     }
   }
-  node.$path = relativeCommonDir;
+  node.$path = { optional: relativeCommonDir };
   delete node.$className;
 }
 function findExposedDataFiles(node, exposed = []) {
@@ -9565,8 +9607,9 @@ function findExposedDataFiles(node, exposed = []) {
     const val = node[key];
     if (typeof val !== "object" || val === null) continue;
     const childNode = val;
-    if (childNode.$path && isData(childNode.$path)) {
-      exposed.push({ parent: node, key, path: childNode.$path });
+    const childPath = getPathString(childNode);
+    if (childPath && isData(childPath)) {
+      exposed.push({ parent: node, key, path: childPath });
     }
     findExposedDataFiles(childNode, exposed);
   }
@@ -10003,6 +10046,24 @@ async function build(targetConfig, baseProjectTree, config, env, sourcePaths, cl
     modeCopy.build = cliArgs.build;
   }
   const rojoTree = structuredClone(baseProjectTree);
+  for (const targetService of Object.values(services)) {
+    let current = rojoTree.tree;
+    if (serviceParents[targetService]) {
+      current = getOrCreateNode(current, serviceParents[targetService]);
+    }
+    getOrCreateNode(current, targetService);
+  }
+  if (config.aliases) {
+    for (const aliasPath of Object.values(config.aliases)) {
+      if (typeof aliasPath === "string") {
+        const parts = aliasPath.split(".");
+        let current = rojoTree.tree;
+        for (const part of parts) {
+          current = getOrCreateNode(current, part);
+        }
+      }
+    }
+  }
   const mergedTags = { ...config.tags || {}, ...modeCopy.tags || {} };
   const knownTags = new Set(
     Object.keys(config.tags || {}).map((t) => t.toLowerCase())
@@ -10038,6 +10099,7 @@ async function build(targetConfig, baseProjectTree, config, env, sourcePaths, cl
   };
   const combinedGlobIgnorePaths = Array.from(
     /* @__PURE__ */ new Set([
+      ...rojoTree.globIgnorePaths || [],
       ...config.globIgnorePaths || [],
       ...modeCopy.globIgnorePaths || []
     ])
@@ -10067,7 +10129,6 @@ async function build(targetConfig, baseProjectTree, config, env, sourcePaths, cl
       listings,
       (filepath, isInit, isSync) => {
         const relativePath2 = import_path4.default.relative(sourcePath, filepath);
-        if (relativePath2 && isIgnored(toPosix(relativePath2))) return;
         const {
           targetService,
           wrapperFolder,
@@ -10077,7 +10138,8 @@ async function build(targetConfig, baseProjectTree, config, env, sourcePaths, cl
           dropped,
           unwrap
         } = resolveRoute(relativePath2, isInit, newContext, isSync);
-        if (dropped) return;
+        if (dropped || projectPath && isIgnored(toPosix(projectPath)))
+          return;
         fileCount++;
         let current = rojoTree.tree;
         if (serviceParents[targetService]) {
@@ -10109,10 +10171,13 @@ async function build(targetConfig, baseProjectTree, config, env, sourcePaths, cl
         const existingNode = existingNodeRaw || {};
         const newNode = {
           ...existingNode,
-          $path: projectPath
+          $path: { optional: projectPath }
         };
         if (newNode.$className === "Folder") {
           delete newNode.$className;
+          if (newNode.$ignoreUnknownInstances === false) {
+            delete newNode.$ignoreUnknownInstances;
+          }
         }
         current[nodeName] = newNode;
         nodeOrigins.set(newNode, {
@@ -10130,8 +10195,11 @@ async function build(targetConfig, baseProjectTree, config, env, sourcePaths, cl
     outputDir,
     removed
   );
-  collapseFolders(prunedTree, context.build, outputDir);
+  collapseFolders(prunedTree, context.build, outputDir, isIgnored);
   rojoTree.tree = prunedTree;
+  if (combinedGlobIgnorePaths.length > 0) {
+    rojoTree.globIgnorePaths = combinedGlobIgnorePaths;
+  }
   const sortedTree = sortObject(rojoTree);
   const missingPaths = findMissingPaths(
     sortedTree.tree,
@@ -10242,7 +10310,7 @@ var ConsoleLogger = class extends AbstractLogger {
 };
 
 // src/execute.ts
-async function execute(sourcePaths, env, activeModes, baseProjectTree, config, cliArgs, anchor, logger = new ConsoleLogger()) {
+async function execute(sourcePaths, env, activeModes, baseProjectTree, config, cliArgs, anchor, logger = new ConsoleLogger(), isInitialRun = false) {
   try {
     for (const activeMode of activeModes) {
       const targetConfig = activeMode.config;
@@ -10281,15 +10349,16 @@ async function execute(sourcePaths, env, activeModes, baseProjectTree, config, c
         }
       }
       if (buildResult.missingPaths.length > 0) {
+        const isCompiledProject = env.isTsProject || env.isDarkluaProject;
         for (const item of buildResult.missingPaths) {
           const ext = import_path5.default.extname(item.absolutePath).toLowerCase();
-          if (ext === ".luau" || ext === ".lua") {
+          if (isCompiledProject && (ext === ".luau" || ext === ".lua")) {
             const dir = import_path5.default.dirname(item.absolutePath);
             if (!import_fs4.default.existsSync(dir)) {
               import_fs4.default.mkdirSync(dir, { recursive: true });
             }
             import_fs4.default.writeFileSync(item.absolutePath, "");
-          } else if (ext === "") {
+          } else if (isCompiledProject && ext === "") {
             if (!import_fs4.default.existsSync(item.absolutePath)) {
               import_fs4.default.mkdirSync(item.absolutePath, {
                 recursive: true
@@ -10312,14 +10381,18 @@ async function execute(sourcePaths, env, activeModes, baseProjectTree, config, c
           shouldWrite = false;
         }
       }
-      if (!shouldWrite) {
+      if (!shouldWrite && cliArgs.watch && !isInitialRun) {
         continue;
       }
-      const outputDir = import_path5.default.dirname(buildResult.output);
-      if (!import_fs4.default.existsSync(outputDir)) {
-        import_fs4.default.mkdirSync(outputDir, { recursive: true });
+      if (shouldWrite) {
+        const outputDir = import_path5.default.dirname(buildResult.output);
+        if (!import_fs4.default.existsSync(outputDir)) {
+          import_fs4.default.mkdirSync(outputDir, { recursive: true });
+        }
+        const tempOutput = `${buildResult.output}.tmp`;
+        import_fs4.default.writeFileSync(tempOutput, finalContent);
+        import_fs4.default.renameSync(tempOutput, buildResult.output);
       }
-      import_fs4.default.writeFileSync(buildResult.output, finalContent);
       const totalRemoved = buildResult.removed.length + dropped.length;
       if (totalRemoved > 0) {
         if (cliArgs.watch) {
@@ -10341,22 +10414,30 @@ async function execute(sourcePaths, env, activeModes, baseProjectTree, config, c
           logger.warn(collision);
         }
       }
-      if (cliArgs.watch) {
+      if (!isInitialRun) {
         const outputName = import_path5.default.basename(buildResult.output);
         logger.success(
           `[${modeName}] Rebuilt "${buildResult.name}" -> ${outputName}`
         );
       } else {
-        logger.success(`Generated Rojo tree for "${buildResult.name}"`);
-        logger.info(`  Processed: ${buildResult.fileCount} files`);
-        logger.info(`  Build dir: ${buildResult.buildDir}`);
-        const activeTags = Object.keys(targetConfig.tags || {}).filter(
-          (t) => targetConfig.tags[t]
-        );
-        if (activeTags.length > 0) {
-          logger.info(`  Tags: ${activeTags.join(", ")}`);
+        if (shouldWrite) {
+          logger.success(
+            `Generated Rojo tree for "${buildResult.name}"`
+          );
+          logger.info(`  Processed: ${buildResult.fileCount} files`);
+          logger.info(`  Build dir: ${buildResult.buildDir}`);
+          const activeTags = Object.keys(
+            targetConfig.tags || {}
+          ).filter((t) => targetConfig.tags[t]);
+          if (activeTags.length > 0) {
+            logger.info(`  Tags: ${activeTags.join(", ")}`);
+          }
+          logger.info(`  Output to: ${buildResult.output}`);
+        } else {
+          logger.success(
+            `Rojo tree for "${buildResult.name}" is already up to date`
+          );
         }
-        logger.info(`  Output to: ${buildResult.output}`);
       }
     }
     return true;
@@ -10440,7 +10521,8 @@ async function main() {
     config,
     cliArgs,
     anchor,
-    logger
+    logger,
+    true
   );
   if (!success) {
     process.exit(1);
@@ -10449,9 +10531,14 @@ async function main() {
     logger.info(
       `Watching for file changes in: "${sourceDirs.join(", ")}" (Ctrl+C to stop)`
     );
+    const isWindows = process.platform === "win32";
     const watcher = import_chokidar.default.watch(sourcePaths, {
       persistent: true,
-      ignoreInitial: true
+      ignoreInitial: true,
+      // Use polling on Windows to avoid "folder in use" locks
+      usePolling: isWindows,
+      interval: isWindows ? 400 : void 0,
+      binaryInterval: isWindows ? 800 : void 0
     });
     let debounceTimeout;
     let isBuilding = false;
@@ -10470,7 +10557,8 @@ async function main() {
             config,
             cliArgs,
             anchor,
-            logger
+            logger,
+            false
           );
         } catch (err) {
           logger.error(err instanceof Error ? err : String(err));

package/dist/cli.js

@@ -1,14 +1,15 @@
 import { parseArgs } from "util";
 export function printHelp(logger) {
     const helpText = `
-Rogen - Feature-based folder routing for Roblox
+Rogen - Feature-based architecture for Roblox
 
 Usage:
   rogen [command] [options]
 
 Commands:
   init                 Generate a .rogen.json config file
-  watch                Watch the source and generate automatically
+  build                Build the project
+  watch                Watch the source and build automatically
 
 Options:
   -c, --config <path>  Specify custom config file
@@ -64,6 +65,9 @@ export function parseCliArgs(args = process.argv.slice(2), logger) {
             else if (subcommand === "version") {
                 parsedArgs.version = true;
             }
+            else if (subcommand === "build") {
+                // build is the default command, so it falls through cleanly
+            }
             else {
                 const errorMsg = `unknown subcommand "${positionals[0]}".\nRun 'rogen --help' to see a list of available commands.`;
                 if (logger) {

package/dist/constants.js

@@ -1,4 +1,14 @@
-export const version = "1.4.1";
+export const version = "1.4.3";
+export const dataExtensions = new Set([
+    ".csv",
+    ".txt",
+    ".json",
+    ".toml",
+    ".yaml",
+    ".yml",
+    ".msgpack",
+    ".md",
+]);
 export const defaultProject = {
     name: "roblox-game",
     tree: { $className: "DataModel" },
@@ -52,6 +62,10 @@ export const serviceParents = {
     StarterPlayerScripts: "StarterPlayer",
     StarterCharacterScripts: "StarterPlayer",
 };
+export const combinedServices = new Set([
+    ...Object.values(services),
+    ...Object.values(serviceParents),
+]);
 export const serverContainers = new Set([
     "ServerScriptService",
     "ServerStorage",

package/dist/execute.js

@@ -2,7 +2,7 @@ import fs from "fs";
 import path from "path";
 import { build } from "./build.js";
 import { ConsoleLogger, getTimeStamp } from "./logger.js";
-export async function execute(sourcePaths, env, activeModes, baseProjectTree, config, cliArgs, anchor, logger = new ConsoleLogger()) {
+export async function execute(sourcePaths, env, activeModes, baseProjectTree, config, cliArgs, anchor, logger = new ConsoleLogger(), isInitialRun = false) {
     try {
         for (const activeMode of activeModes) {
             const targetConfig = activeMode.config;
@@ -24,16 +24,22 @@ export async function execute(sourcePaths, env, activeModes, baseProjectTree, co
                 }
             }
             if (buildResult.missingPaths.length > 0) {
+                // Only synthesize placeholder stubs/dirs for compiled projects (ts/darklua),
+                // where the build output legitimately does not exist yet at generation time. For a luau
+                // project the build dir IS the source, so a missing path means the file was removed —
+                // recreating it would fight an in-progress delete and desync Rojo. Drop the stale node instead.
+                const isCompiledProject = env.isTsProject || env.isDarkluaProject;
                 for (const item of buildResult.missingPaths) {
                     const ext = path.extname(item.absolutePath).toLowerCase();
-                    if (ext === ".luau" || ext === ".lua") {
+                    if (isCompiledProject &&
+                        (ext === ".luau" || ext === ".lua")) {
                         const dir = path.dirname(item.absolutePath);
                         if (!fs.existsSync(dir)) {
                             fs.mkdirSync(dir, { recursive: true });
                         }
                         fs.writeFileSync(item.absolutePath, "");
                     }
-                    else if (ext === "") {
+                    else if (isCompiledProject && ext === "") {
                         if (!fs.existsSync(item.absolutePath)) {
                             fs.mkdirSync(item.absolutePath, {
                                 recursive: true,
@@ -54,14 +60,20 @@ export async function execute(sourcePaths, env, activeModes, baseProjectTree, co
                     shouldWrite = false;
                 }
             }
-            if (!shouldWrite) {
+            if (!shouldWrite && cliArgs.watch && !isInitialRun) {
                 continue;
             }
-            const outputDir = path.dirname(buildResult.output);
-            if (!fs.existsSync(outputDir)) {
-                fs.mkdirSync(outputDir, { recursive: true });
+            if (shouldWrite) {
+                const outputDir = path.dirname(buildResult.output);
+                if (!fs.existsSync(outputDir)) {
+                    fs.mkdirSync(outputDir, { recursive: true });
+                }
+                // Write atomically (temp + rename) so a watcher (e.g. Rojo) never reads a
+                // half-written project file during rapid regenerations.
+                const tempOutput = `${buildResult.output}.tmp`;
+                fs.writeFileSync(tempOutput, finalContent);
+                fs.renameSync(tempOutput, buildResult.output);
             }
-            fs.writeFileSync(buildResult.output, finalContent);
             const totalRemoved = buildResult.removed.length + dropped.length;
             if (totalRemoved > 0) {
                 if (cliArgs.watch) {
@@ -82,19 +94,24 @@ export async function execute(sourcePaths, env, activeModes, baseProjectTree, co
                     logger.warn(collision);
                 }
             }
-            if (cliArgs.watch) {
+            if (!isInitialRun) {
                 const outputName = path.basename(buildResult.output);
                 logger.success(`[${modeName}] Rebuilt "${buildResult.name}" -> ${outputName}`);
             }
             else {
-                logger.success(`Generated Rojo tree for "${buildResult.name}"`);
-                logger.info(`  Processed: ${buildResult.fileCount} files`);
-                logger.info(`  Build dir: ${buildResult.buildDir}`);
-                const activeTags = Object.keys(targetConfig.tags || {}).filter((t) => targetConfig.tags[t]);
-                if (activeTags.length > 0) {
-                    logger.info(`  Tags: ${activeTags.join(", ")}`);
+                if (shouldWrite) {
+                    logger.success(`Generated Rojo tree for "${buildResult.name}"`);
+                    logger.info(`  Processed: ${buildResult.fileCount} files`);
+                    logger.info(`  Build dir: ${buildResult.buildDir}`);
+                    const activeTags = Object.keys(targetConfig.tags || {}).filter((t) => targetConfig.tags[t]);
+                    if (activeTags.length > 0) {
+                        logger.info(`  Tags: ${activeTags.join(", ")}`);
+                    }
+                    logger.info(`  Output to: ${buildResult.output}`);
+                }
+                else {
+                    logger.success(`Rojo tree for "${buildResult.name}" is already up to date`);
                 }
-                logger.info(`  Output to: ${buildResult.output}`);
             }
         }
         return true;

package/dist/index.js

@@ -67,15 +67,20 @@ async function main() {
     });
     const env = getEnvironment(anchor, cliArgs.mode);
     const activeModes = resolveActiveModes(config, cliArgs.mode, env);
-    const success = await execute(sourcePaths, env, activeModes, config.project, config, cliArgs, anchor, logger);
+    const success = await execute(sourcePaths, env, activeModes, config.project, config, cliArgs, anchor, logger, true);
     if (!success) {
         process.exit(1);
     }
     if (cliArgs.watch) {
         logger.info(`Watching for file changes in: "${sourceDirs.join(", ")}" (Ctrl+C to stop)`);
+        const isWindows = process.platform === "win32";
         const watcher = chokidar.watch(sourcePaths, {
             persistent: true,
             ignoreInitial: true,
+            // Use polling on Windows to avoid "folder in use" locks
+            usePolling: isWindows,
+            interval: isWindows ? 400 : undefined,
+            binaryInterval: isWindows ? 800 : undefined,
         });
         let debounceTimeout;
         let isBuilding = false;
@@ -87,7 +92,7 @@ async function main() {
                     return;
                 isBuilding = true;
                 try {
-                    execute(sourcePaths, env, activeModes, config.project, config, cliArgs, anchor, logger);
+                    execute(sourcePaths, env, activeModes, config.project, config, cliArgs, anchor, logger, false);
                 }
                 catch (err) {
                     logger.error(err instanceof Error ? err : String(err));

package/dist/tree.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { combinedServices, dataExtensions } from "./constants.js";
 function hasPathPrefix(p, dir) {
     return p === dir || p.startsWith(dir + "/");
 }
@@ -12,9 +13,36 @@ export function applyCasing(value, casing) {
         : value[0].toLowerCase();
     return firstCharacter + value.slice(1);
 }
+export function getPathString(node) {
+    const p = node.$path;
+    if (typeof p === "string")
+        return p;
+    if (p && typeof p === "object" && typeof p.optional === "string")
+        return p.optional;
+    return undefined;
+}
 export function getOrCreateNode(parent, key, className) {
+    const isRootService = combinedServices.has(key) ||
+        (className && combinedServices.has(className));
     if (!parent[key]) {
-        parent[key] = className == null ? {} : { $className: className };
+        parent[key] =
+            className == null
+                ? {}
+                : {
+                    $className: className,
+                    ...(isRootService
+                        ? {}
+                        : { $ignoreUnknownInstances: false }),
+                };
+    }
+    else if (className != null) {
+        const existing = parent[key];
+        if (existing.$ignoreUnknownInstances === undefined &&
+            existing.$path === undefined) {
+            if (!isRootService) {
+                existing.$ignoreUnknownInstances = false;
+            }
+        }
     }
     return parent[key];
 }
@@ -25,17 +53,23 @@ export function pruneObject(node, buildDir, outputDir, removed = [], treePath =
             continue;
         const childTreePath = treePath ? `${treePath}.${key}` : key;
         const childNode = val;
-        if (childNode.$path) {
-            if (hasPathPrefix(childNode.$path, buildDir))
-                continue;
-            const absolutePath = path.resolve(outputDir, childNode.$path);
-            if (!fs.existsSync(absolutePath)) {
-                delete node[key];
-                removed.push({
-                    treePath: childTreePath,
-                    rojoPath: childNode.$path,
-                });
+        const childPath = getPathString(childNode);
+        if (childPath) {
+            if (hasPathPrefix(childPath, buildDir))
                 continue;
+            // Optional paths are allowed to be absent so only required (string) template
+            // paths are pruned when missing.
+            const isOptional = typeof childNode.$path === "object";
+            if (!isOptional) {
+                const absolutePath = path.resolve(outputDir, childPath);
+                if (!fs.existsSync(absolutePath)) {
+                    delete node[key];
+                    removed.push({
+                        treePath: childTreePath,
+                        rojoPath: childPath,
+                    });
+                    continue;
+                }
             }
         }
         pruneObject(childNode, buildDir, outputDir, removed, childTreePath);
@@ -61,14 +95,15 @@ export function findMissingPaths(node, buildDir, outputDir, missing = [], treePa
             continue;
         const childTreePath = treePath ? `${treePath}.${key}` : key;
         const childNode = val;
-        if (childNode.$path && hasPathPrefix(childNode.$path, buildDir)) {
-            const absolutePath = path.resolve(outputDir, childNode.$path);
+        const childPath = getPathString(childNode);
+        if (childPath && hasPathPrefix(childPath, buildDir)) {
+            const absolutePath = path.resolve(outputDir, childPath);
             if (!fs.existsSync(absolutePath)) {
                 missing.push({
                     parent: node,
                     key,
                     treePath: childTreePath,
-                    path: childNode.$path,
+                    path: childPath,
                     absolutePath,
                 });
             }
@@ -83,9 +118,12 @@ const isModel = (filename) => /\.(rbxm|rbxmx)$/i.test(filename);
 export function isData(filename) {
     if (isScript(filename) || isModel(filename))
         return false;
+    if (filename.toLowerCase().endsWith(".d.ts"))
+        return false;
     if (filename.startsWith("."))
         return false;
-    return /\.[a-z0-9]+$/i.test(filename);
+    const ext = path.extname(filename).toLowerCase();
+    return dataExtensions.has(ext);
 }
 export const isValidSource = (filename) => isScript(filename) || isModel(filename) || isData(filename);
 export const isInitFile = (filename) => isScript(filename) && /^(index|init)([.-][a-z0-9_]+)?\./i.test(filename);
@@ -103,7 +141,7 @@ function getRojoBaseName(filename) {
     }
     return filename;
 }
-export function collapseFolders(node, buildDir, outputDir) {
+export function collapseFolders(node, buildDir, outputDir, isIgnored = () => false) {
     let childCount = 0;
     let canCollapse = node.$path === undefined; // Prevent overwriting a folder with an explicit $path
     let commonDir = null;
@@ -115,13 +153,14 @@ export function collapseFolders(node, buildDir, outputDir) {
             continue;
         const childNode = val;
         // Process deepest nested children first
-        collapseFolders(childNode, buildDir, outputDir);
+        collapseFolders(childNode, buildDir, outputDir, isIgnored);
         childCount++;
-        if (!childNode.$path) {
+        const childPath = getPathString(childNode);
+        if (!childPath) {
             canCollapse = false;
         }
         else {
-            const childAbsPath = path.resolve(outputDir, childNode.$path);
+            const childAbsPath = path.resolve(outputDir, childPath);
             const parentDir = path.dirname(childAbsPath);
             // All children should share the same directory
             if (commonDir === null) {
@@ -143,10 +182,12 @@ export function collapseFolders(node, buildDir, outputDir) {
     if (!hasPathPrefix(toPosix(commonDir), toPosix(absoluteBuildDir))) {
         return;
     }
+    const relativeCommonDir = toPosix(path.relative(outputDir, commonDir));
     try {
         const diskItems = fs.readdirSync(commonDir);
-        // filter out marker files so they do not prevent folders from collapsing
-        const visibleDiskItems = diskItems.filter((item) => !item.startsWith("."));
+        // filter out marker files and ignored files so they do not prevent folders from collapsing
+        const visibleDiskItems = diskItems.filter((item) => !item.startsWith(".") &&
+            !isIgnored(toPosix(path.join(relativeCommonDir, item))));
         if (visibleDiskItems.length !== childCount) {
             return;
         }
@@ -155,13 +196,12 @@ export function collapseFolders(node, buildDir, outputDir) {
         return;
     }
     // Replace all child files with a single folder $path
-    const relativeCommonDir = toPosix(path.relative(outputDir, commonDir));
     for (const key in node) {
         if (!key.startsWith("$")) {
             delete node[key];
         }
     }
-    node.$path = relativeCommonDir;
+    node.$path = { optional: relativeCommonDir };
     delete node.$className;
 }
 export function findExposedDataFiles(node, exposed = []) {
@@ -172,9 +212,10 @@ export function findExposedDataFiles(node, exposed = []) {
         if (typeof val !== "object" || val === null)
             continue;
         const childNode = val;
+        const childPath = getPathString(childNode);
         // Check if the current node exposes a raw data file path
-        if (childNode.$path && isData(childNode.$path)) {
-            exposed.push({ parent: node, key, path: childNode.$path });
+        if (childPath && isData(childPath)) {
+            exposed.push({ parent: node, key, path: childPath });
         }
         findExposedDataFiles(childNode, exposed);
     }

package/package.json

@@ -1,10 +1,20 @@
 {
 	"name": "@ldgerrits/rogen",
-	"version": "1.4.1",
+	"version": "1.4.3",
+	"description": "A CLI tool that enables feature-based architecture for Roblox",
 	"publishConfig": {
 		"access": "public"
 	},
-	"description": "A CLI tool enabling feature-based architecture through automated routing of client, server, and shared code to Roblox services",
+	"homepage": "https://rogen-playfully.vercel.app/",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/LDGerrits/rogen.git"
+	},
+	"keywords": [
+		"roblox",
+		"organization",
+		"feature-based architecture"
+	],
 	"author": "ldgerrits",
 	"license": "MIT",
 	"type": "module",