@timeax/scaffold 0.0.1 → 0.0.3

package/dist/index.d.cts

@@ -305,6 +305,15 @@ interface ScaffoldConfig {
      * runner / CLI.
      */
     watch?: boolean;
+    /**
+     * Number of spaces per indent level in structure files.
+     * Default: 2.
+     *
+     * Examples:
+     * - 2  → "··entry"
+     * - 4  → "····entry"
+     */
+    indentStep?: number;
 }
 /**
  * Options when scanning an existing directory into a structure.txt tree.
@@ -336,6 +345,8 @@ interface ScanFromConfigOptions extends ScanStructureOptions {
     scaffoldDir?: string;
 }
 
+declare const SCAFFOLD_ROOT_DIR = ".scaffold";
+
 type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
 interface LoggerOptions {
     level?: LogLevel;
@@ -394,6 +405,49 @@ interface RunOptions {
  */
 declare function runOnce(cwd: string, options?: RunOptions): Promise<void>;
 
+interface LoadScaffoldConfigOptions {
+    /**
+     * Optional explicit scaffold directory path (absolute or relative to cwd).
+     * If provided, this overrides config.root for locating the scaffold folder.
+     */
+    scaffoldDir?: string;
+    /**
+     * Optional explicit config file path (absolute or relative to cwd).
+     * If not provided, we look for config.* inside the scaffoldDir.
+     */
+    configPath?: string;
+}
+interface LoadScaffoldConfigResult {
+    /**
+     * Parsed scaffold configuration.
+     */
+    config: ScaffoldConfig;
+    /**
+     * Absolute path to the scaffold directory (where config & *.txt live).
+     */
+    scaffoldDir: string;
+    /**
+     * Effective project root BASE where structures are applied.
+     * This is derived from config.root + config.base.
+     */
+    projectRoot: string;
+}
+/**
+ * Load scaffold configuration based on CWD + optional overrides + config.root/base.
+ *
+ * Resolution rules:
+ * - configRoot:
+ *   - Start from cwd.
+ *   - Apply config.root (if defined) as a path relative to cwd.
+ * - scaffoldDir:
+ *   - If options.scaffoldDir is provided → use it as-is (resolved from cwd).
+ *   - Else → <configRoot>/scaffold.
+ * - projectRoot (base):
+ *   - If config.base is defined → resolve relative to configRoot.
+ *   - Else → configRoot.
+ */
+declare function loadScaffoldConfig(cwd: string, options?: LoadScaffoldConfigOptions): Promise<LoadScaffoldConfigResult>;
+
 /**
  * Generate a structure.txt-style tree from an existing directory.
  *
@@ -435,5 +489,34 @@ declare function scanProjectFromConfig(cwd: string, options?: ScanFromConfigOpti
  * structure files.
  */
 declare function writeScannedStructuresFromConfig(cwd: string, options?: ScanFromConfigOptions): Promise<void>;
+interface EnsureStructuresResult {
+    created: string[];
+    existing: string[];
+}
+/**
+ * Ensure all structure files declared in the config exist.
+ *
+ * - Grouped mode: one file per group (group.structureFile || `${group.name}.txt`)
+ * - Single-root mode: config.structureFile || "structure.txt"
+ *
+ * Existing files are left untouched. Only missing files are created with
+ * a small header comment.
+ */
+declare function ensureStructureFilesFromConfig(cwd: string, options?: {
+    scaffoldDirOverride?: string;
+}): Promise<EnsureStructuresResult>;
+
+/**
+ * Convert a structure.txt content into a nested StructureEntry[].
+ *
+ * Rules:
+ * - Indentation is **indentStep** spaces per level (default: 2).
+ * - Indent must be a multiple of indentStep.
+ * - You cannot "skip" levels (no jumping from level 0 to 2 directly).
+ * - **Only directories can have children**:
+ *   - If you indent under a file, an error is thrown.
+ * - Folders must end with "/" in the txt; paths are normalized to POSIX.
+ */
+declare function parseStructureText(text: string, indentStep?: number): StructureEntry[];
 
-export { type BaseEntryOptions, type DirEntry, type FileEntry, type HookContext, type HookFilter, type RegularHookConfig, type RegularHookFn, type RegularHookKind, type RunOptions, type ScaffoldConfig, type ScanFromConfigOptions, type ScanFromConfigResult, type ScanStructureOptions, type StructureEntry, type StructureGroupConfig, type StubConfig, type StubHookConfig, type StubHookFn, type StubHookKind, runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };
+export { type BaseEntryOptions, type DirEntry, type EnsureStructuresResult, type FileEntry, type HookContext, type HookFilter, type LoadScaffoldConfigOptions, type LoadScaffoldConfigResult, type RegularHookConfig, type RegularHookFn, type RegularHookKind, type RunOptions, SCAFFOLD_ROOT_DIR, type ScaffoldConfig, type ScanFromConfigOptions, type ScanFromConfigResult, type ScanStructureOptions, type StructureEntry, type StructureGroupConfig, type StubConfig, type StubHookConfig, type StubHookFn, type StubHookKind, ensureStructureFilesFromConfig, loadScaffoldConfig, parseStructureText, runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };

package/dist/index.d.ts

@@ -305,6 +305,15 @@ interface ScaffoldConfig {
      * runner / CLI.
      */
     watch?: boolean;
+    /**
+     * Number of spaces per indent level in structure files.
+     * Default: 2.
+     *
+     * Examples:
+     * - 2  → "··entry"
+     * - 4  → "····entry"
+     */
+    indentStep?: number;
 }
 /**
  * Options when scanning an existing directory into a structure.txt tree.
@@ -336,6 +345,8 @@ interface ScanFromConfigOptions extends ScanStructureOptions {
     scaffoldDir?: string;
 }
 
+declare const SCAFFOLD_ROOT_DIR = ".scaffold";
+
 type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
 interface LoggerOptions {
     level?: LogLevel;
@@ -394,6 +405,49 @@ interface RunOptions {
  */
 declare function runOnce(cwd: string, options?: RunOptions): Promise<void>;
 
+interface LoadScaffoldConfigOptions {
+    /**
+     * Optional explicit scaffold directory path (absolute or relative to cwd).
+     * If provided, this overrides config.root for locating the scaffold folder.
+     */
+    scaffoldDir?: string;
+    /**
+     * Optional explicit config file path (absolute or relative to cwd).
+     * If not provided, we look for config.* inside the scaffoldDir.
+     */
+    configPath?: string;
+}
+interface LoadScaffoldConfigResult {
+    /**
+     * Parsed scaffold configuration.
+     */
+    config: ScaffoldConfig;
+    /**
+     * Absolute path to the scaffold directory (where config & *.txt live).
+     */
+    scaffoldDir: string;
+    /**
+     * Effective project root BASE where structures are applied.
+     * This is derived from config.root + config.base.
+     */
+    projectRoot: string;
+}
+/**
+ * Load scaffold configuration based on CWD + optional overrides + config.root/base.
+ *
+ * Resolution rules:
+ * - configRoot:
+ *   - Start from cwd.
+ *   - Apply config.root (if defined) as a path relative to cwd.
+ * - scaffoldDir:
+ *   - If options.scaffoldDir is provided → use it as-is (resolved from cwd).
+ *   - Else → <configRoot>/scaffold.
+ * - projectRoot (base):
+ *   - If config.base is defined → resolve relative to configRoot.
+ *   - Else → configRoot.
+ */
+declare function loadScaffoldConfig(cwd: string, options?: LoadScaffoldConfigOptions): Promise<LoadScaffoldConfigResult>;
+
 /**
  * Generate a structure.txt-style tree from an existing directory.
  *
@@ -435,5 +489,34 @@ declare function scanProjectFromConfig(cwd: string, options?: ScanFromConfigOpti
  * structure files.
  */
 declare function writeScannedStructuresFromConfig(cwd: string, options?: ScanFromConfigOptions): Promise<void>;
+interface EnsureStructuresResult {
+    created: string[];
+    existing: string[];
+}
+/**
+ * Ensure all structure files declared in the config exist.
+ *
+ * - Grouped mode: one file per group (group.structureFile || `${group.name}.txt`)
+ * - Single-root mode: config.structureFile || "structure.txt"
+ *
+ * Existing files are left untouched. Only missing files are created with
+ * a small header comment.
+ */
+declare function ensureStructureFilesFromConfig(cwd: string, options?: {
+    scaffoldDirOverride?: string;
+}): Promise<EnsureStructuresResult>;
+
+/**
+ * Convert a structure.txt content into a nested StructureEntry[].
+ *
+ * Rules:
+ * - Indentation is **indentStep** spaces per level (default: 2).
+ * - Indent must be a multiple of indentStep.
+ * - You cannot "skip" levels (no jumping from level 0 to 2 directly).
+ * - **Only directories can have children**:
+ *   - If you indent under a file, an error is thrown.
+ * - Folders must end with "/" in the txt; paths are normalized to POSIX.
+ */
+declare function parseStructureText(text: string, indentStep?: number): StructureEntry[];
 
-export { type BaseEntryOptions, type DirEntry, type FileEntry, type HookContext, type HookFilter, type RegularHookConfig, type RegularHookFn, type RegularHookKind, type RunOptions, type ScaffoldConfig, type ScanFromConfigOptions, type ScanFromConfigResult, type ScanStructureOptions, type StructureEntry, type StructureGroupConfig, type StubConfig, type StubHookConfig, type StubHookFn, type StubHookKind, runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };
+export { type BaseEntryOptions, type DirEntry, type EnsureStructuresResult, type FileEntry, type HookContext, type HookFilter, type LoadScaffoldConfigOptions, type LoadScaffoldConfigResult, type RegularHookConfig, type RegularHookFn, type RegularHookKind, type RunOptions, SCAFFOLD_ROOT_DIR, type ScaffoldConfig, type ScanFromConfigOptions, type ScanFromConfigResult, type ScanStructureOptions, type StructureEntry, type StructureGroupConfig, type StubConfig, type StubHookConfig, type StubHookFn, type StubHookKind, ensureStructureFilesFromConfig, loadScaffoldConfig, parseStructureText, runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };

package/dist/index.mjs

@@ -6,7 +6,8 @@ import { pathToFileURL } from 'url';
 import { transform } from 'esbuild';
 import { minimatch } from 'minimatch';
 
-// src/core/runner.ts
+// src/schema/index.ts
+var SCAFFOLD_ROOT_DIR = ".scaffold";
 
 // src/util/logger.ts
 var supportsColor = typeof process !== "undefined" && process.stdout && process.stdout.isTTY && process.env.NO_COLOR !== "1";
@@ -131,14 +132,14 @@ function toProjectRelativePath(projectRoot, absolutePath) {
 var logger = defaultLogger.child("[config]");
 async function loadScaffoldConfig(cwd, options = {}) {
   const absCwd = path2.resolve(cwd);
-  const initialScaffoldDir = options.scaffoldDir ? path2.resolve(absCwd, options.scaffoldDir) : path2.join(absCwd, "scaffold");
+  const initialScaffoldDir = options.scaffoldDir ? path2.resolve(absCwd, options.scaffoldDir) : path2.join(absCwd, SCAFFOLD_ROOT_DIR);
   const configPath = options.configPath ?? resolveConfigPath(initialScaffoldDir);
   const config = await importConfig(configPath);
   let configRoot = absCwd;
   if (config.root) {
     configRoot = path2.resolve(absCwd, config.root);
   }
-  const scaffoldDir = options.scaffoldDir ? path2.resolve(absCwd, options.scaffoldDir) : path2.join(configRoot, "scaffold");
+  const scaffoldDir = options.scaffoldDir ? path2.resolve(absCwd, options.scaffoldDir) : path2.join(configRoot, SCAFFOLD_ROOT_DIR);
   const baseRoot = config.base ? path2.resolve(configRoot, config.base) : configRoot;
   logger.debug(
     `Loaded config: configRoot=${configRoot}, baseRoot=${baseRoot}, scaffoldDir=${scaffoldDir}`
@@ -203,14 +204,50 @@ async function importTsConfig(configPath) {
 }
 
 // src/core/structure-txt.ts
+function stripInlineComment(content) {
+  let cutIndex = -1;
+  const len = content.length;
+  for (let i = 0; i < len; i++) {
+    const ch = content[i];
+    const prev = i > 0 ? content[i - 1] : "";
+    if (ch === "#") {
+      if (i === 0) continue;
+      if (prev === " " || prev === "	") {
+        cutIndex = i;
+        break;
+      }
+    }
+    if (ch === "/" && i + 1 < len && content[i + 1] === "/" && (prev === " " || prev === "	")) {
+      cutIndex = i;
+      break;
+    }
+  }
+  if (cutIndex === -1) {
+    return content.trimEnd();
+  }
+  return content.slice(0, cutIndex).trimEnd();
+}
 function parseLine(line, lineNo) {
-  const match = line.match(/^(\s*)(.+)$/);
+  const match = line.match(/^(\s*)(.*)$/);
   if (!match) return null;
   const indentSpaces = match[1].length;
-  const rest = match[2].trim();
-  if (!rest || rest.startsWith("#")) return null;
-  const parts = rest.split(/\s+/);
+  let rest = match[2];
+  if (!rest.trim()) return null;
+  const trimmedRest = rest.trimStart();
+  if (trimmedRest.startsWith("#") || trimmedRest.startsWith("//")) {
+    return null;
+  }
+  const stripped = stripInlineComment(rest);
+  const trimmed = stripped.trim();
+  if (!trimmed) return null;
+  const parts = trimmed.split(/\s+/);
+  if (!parts.length) return null;
   const pathToken = parts[0];
+  if (pathToken.includes(":")) {
+    throw new Error(
+      `structure.txt: ":" is reserved for annotations (@stub:, @include:, etc). Invalid path "${pathToken}" on line ${lineNo}.`
+    );
+  }
   let stub;
   const include = [];
   const exclude = [];
@@ -242,7 +279,7 @@ function parseLine(line, lineNo) {
     exclude: exclude.length ? exclude : void 0
   };
 }
-function parseStructureText(text) {
+function parseStructureText(text, indentStep = 2) {
   const lines = text.split(/\r?\n/);
   const parsed = [];
   for (let i = 0; i < lines.length; i++) {
@@ -252,15 +289,14 @@ function parseStructureText(text) {
   }
   const rootEntries = [];
   const stack = [];
-  const INDENT_STEP = 2;
   for (const p of parsed) {
     const { indentSpaces, lineNo } = p;
-    if (indentSpaces % INDENT_STEP !== 0) {
+    if (indentSpaces % indentStep !== 0) {
       throw new Error(
-        `structure.txt: Invalid indent on line ${lineNo}. Indent must be multiples of ${INDENT_STEP} spaces.`
+        `structure.txt: Invalid indent on line ${lineNo}. Indent must be multiples of ${indentStep} spaces.`
       );
     }
-    const level = indentSpaces / INDENT_STEP;
+    const level = indentSpaces / indentStep;
     if (level > stack.length) {
       if (level !== stack.length + 1) {
         throw new Error(
@@ -767,7 +803,46 @@ async function writeScannedStructuresFromConfig(cwd, options = {}) {
     );
   }
 }
+async function ensureStructureFilesFromConfig(cwd, options = {}) {
+  const { config, scaffoldDir } = await loadScaffoldConfig(cwd, {
+    scaffoldDir: options.scaffoldDirOverride
+  });
+  ensureDirSync(scaffoldDir);
+  const created = [];
+  const existing = [];
+  const seen = /* @__PURE__ */ new Set();
+  const ensureFile = (fileName) => {
+    if (!fileName) return;
+    const filePath = path2.join(scaffoldDir, fileName);
+    const key = path2.resolve(filePath);
+    if (seen.has(key)) return;
+    seen.add(key);
+    if (fs2.existsSync(filePath)) {
+      existing.push(filePath);
+      return;
+    }
+    const header = `# ${fileName}
+# Structure file for @timeax/scaffold
+# Define your desired folders/files here.
+`;
+    fs2.writeFileSync(filePath, header, "utf8");
+    created.push(filePath);
+  };
+  if (config.groups && config.groups.length > 0) {
+    for (const group of config.groups) {
+      const fileName = group.structureFile ?? `${group.name}.txt`;
+      ensureFile(fileName);
+    }
+  } else {
+    const fileName = config.structureFile ?? "structure.txt";
+    ensureFile(fileName);
+  }
+  logger4.debug(
+    `ensureStructureFilesFromConfig: created=${created.length}, existing=${existing.length}`
+  );
+  return { created, existing };
+}
 
-export { runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };
+export { SCAFFOLD_ROOT_DIR, ensureStructureFilesFromConfig, loadScaffoldConfig, parseStructureText, runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map