@timeax/scaffold 0.0.1 → 0.0.3

package/readme.md

@@ -1,4 +1,4 @@
-# Scaffold - `@timeax/scaffold`
+# @timeax/scaffold
 
 A tiny, opinionated scaffolding tool that keeps your project structure in sync with a **declarative tree** (like `structure.txt`) – Prisma‑style.
 
@@ -8,11 +8,13 @@ A tiny, opinionated scaffolding tool that keeps your project structure in sync w
 * Reverse‑engineer existing projects into `*.txt` structures.
 * Watch for changes and re‑apply automatically.
 
+> **Supported structure files:** `.tss`, `.stx`, `structure.txt`, and any `.txt` files inside `.scaffold/`.
+
 ---
 
 ## Features
 
-* **Prisma‑style scaffold directory**: all config and structure lives under `scaffold/` by default.
+* **Prisma‑style scaffold directory**: all config and structure lives under `.scaffold/` by default.
 * **Config‑driven groups**: declare multiple roots (e.g. `app`, `frontend`) with their own structure files.
 * **Plain‑text structure files**: strict, easy‑to‑read tree syntax with indentation and annotations.
 * **Safe apply**:
@@ -26,8 +28,14 @@ A tiny, opinionated scaffolding tool that keeps your project structure in sync w
   * Regular hooks around file create/delete.
   * Stub hooks around content generation.
 * **Stubs**: programmatic content generators for files (e.g. React pages, controllers, etc.).
-* **Watch mode**: watch `scaffold/` for changes and re‑run automatically.
+* **Watch mode**: watch `.scaffold/` for changes and re‑run automatically.
 * **Scanner**: generate `structure.txt` (or per‑group `*.txt`) from an existing codebase.
+* **VS Code integration** (via a companion extension):
+
+  * Syntax highlighting for `.tss`, `.stx`, `structure.txt`, and `.scaffold/**/*.txt`.
+  * Inline diagnostics using the same parser as the CLI.
+  * “Go to file” from a structure line.
+  * Simple formatting and sorting commands.
 
 ---
 
@@ -57,7 +65,7 @@ pnpm scaffold init
 This will create:
 
 ```txt
-scaffold/
+.scaffold/
   config.ts       # main ScaffoldConfig
   structure.txt   # example structure (single-root mode)
 ```
@@ -74,7 +82,7 @@ scaffold init --dir tools/scaffold
 
 ### 2. Define your structure
 
-By default, `scaffold/structure.txt` is used in single‑root mode.
+By default, `.scaffold/structure.txt` is used in single‑root mode.
 
 Example:
 
@@ -98,12 +106,16 @@ README.md
 
 **Rules:**
 
-* Indent with **2 spaces per level** (strict).
+* Indent with **2 spaces per level** (strict by default; configurable).
 * Directories **must** end with `/`.
 * Files **must not** end with `/`.
 * You **cannot indent under a file** (files cannot have children).
 * You can’t “skip” levels (no jumping from depth 0 to depth 2 in one go).
-* Lines starting with `#` are comments.
+* Lines starting with `#` or `//` (after indentation) are comments.
+* Inline comments are supported:
+
+  * `index.ts  # comment`
+  * `index.ts  // comment`
 
 #### Annotations
 
@@ -124,20 +136,22 @@ Supported inline annotations:
 
 These map onto the `StructureEntry` fields in TypeScript.
 
+> `:` is reserved for annotations (e.g. `@stub:page`). Paths themselves must **not** contain `:`.
+
 ---
 
 ### 3. Configure groups (optional but recommended)
 
-In `scaffold/config.ts` you can enable grouped mode:
+In `.scaffold/config.ts` you can enable grouped mode:
 
 ```ts
 import type { ScaffoldConfig } from '@timeax/scaffold';
 
 const config: ScaffoldConfig = {
-  root: '.', // project root (optional, defaults to cwd)
+  base: '.', // project root (optional, defaults to cwd)
 
   groups: [
-    { name: 'app', root: 'app', structureFile: 'app.txt' },
+    { name: 'app',      root: 'app',          structureFile: 'app.txt' },
     { name: 'frontend', root: 'resources/js', structureFile: 'frontend.txt' },
   ],
 
@@ -148,21 +162,21 @@ const config: ScaffoldConfig = {
 export default config;
 ```
 
-Then create per‑group structure files in `scaffold/`:
+Then create per‑group structure files in `.scaffold/`:
 
 ```txt
-# scaffold/app.txt
+# .scaffold/app.txt
 App/Services/
   UserService.php
 
-# scaffold/frontend.txt
+# .scaffold/frontend.txt
 src/
   index.tsx
   pages/
     home.tsx
 ```
 
-> When `groups` is defined and non‑empty, single‑root `structure`/`structureFile` is ignored.
+> When `groups` is defined and non‑empty, single‑root `structure` / `structureFile` is ignored.
 
 ---
 
@@ -173,16 +187,16 @@ src/
 scaffold
 
 # or with explicit scaffold dir / config
-scaffold --dir scaffold --config scaffold/config.ts
+scaffold --dir .scaffold --config .scaffold/config.ts
 ```
 
 What happens:
 
-* Config is loaded from `scaffold/config.*` (Prisma‑style resolution).
+* Config is loaded from `.scaffold/config.*` (Prisma‑style resolution).
 * Structure(s) are resolved (grouped or single‑root).
 * Files/directories missing on disk are created.
 * New files are registered in `.scaffold-cache.json` (under project root by default).
-* Any previously created files that are no longer in the structure are candidates for deletion.
+* Any previously created files that are no longer in the structure are candidates for deletion:
 
   * Small files are deleted automatically.
   * Large files (configurable threshold) trigger an interactive prompt.
@@ -195,8 +209,8 @@ scaffold --watch
 
 * Watches:
 
-  * `scaffold/config.*`
-  * `scaffold/*.txt`
+  * `.scaffold/config.*`
+  * `.scaffold/*.txt`
 * Debounces rapid edits.
 * Prevents overlapping runs.
 
@@ -213,11 +227,13 @@ scaffold [options]
 Options:
 
 * `-c, --config <path>` – override config file path.
-* `-d, --dir <path>` – override scaffold directory (default: `./scaffold`).
+* `-d, --dir <path>` – override scaffold directory (default: `./.scaffold`).
 * `-w, --watch` – watch scaffold directory for changes.
 * `--quiet` – silence logs.
 * `--debug` – verbose debug logs.
 
+---
+
 ### `scaffold init`
 
 Initialize the scaffold directory + config + structure.
@@ -228,42 +244,85 @@ scaffold init [options]
 
 Options:
 
-* `-d, --dir <path>` – scaffold directory (default: `./scaffold`, inherited from root options).
+* `-d, --dir <path>` – scaffold directory (default: `./.scaffold`, inherited from root options).
 * `--force` – overwrite existing `config.ts` / `structure.txt`.
 
+---
+
 ### `scaffold scan`
 
 Generate `structure.txt`‑style definitions from an existing project.
 
 Two modes:
 
-1. **Config‑aware mode** (default if no `--root` / `--out` given):
+#### 1. Config‑aware mode (default if no `--root` / `--out` given)
+
+```bash
+scaffold scan
+scaffold scan --from-config
+scaffold scan --from-config --groups app frontend
+```
+
+* Loads `.scaffold/config.ts`.
+* For each `group` in config:
+
+  * Scans `group.root` on disk.
+  * Writes to `.scaffold/<group.structureFile || group.name + '.txt'>`.
+* `--groups` filters which groups to scan.
+
+#### 2. Manual mode (single root)
+
+```bash
+scaffold scan -r src
+scaffold scan -r src -o .scaffold/src.txt
+```
+
+Options:
 
-   ```bash
-   scaffold scan
-   scaffold scan --from-config
-   scaffold scan --from-config --groups app frontend
-   ```
+* `-r, --root <path>` – directory to scan.
+* `-o, --out <path>` – output file (otherwise prints to stdout).
+* `--ignore <patterns...>` – extra globs to ignore (in addition to defaults like `node_modules/**`, `.git/**`, etc.).
 
-   * Loads `scaffold/config.ts`.
-   * For each `group` in config:
+---
+
+### `scaffold structures`
 
-     * Scans `group.root` on disk.
-     * Writes to `scaffold/<group.structureFile || group.name + '.txt'>`.
-   * `--groups` filters which groups to scan.
+Ensure that all structure files declared in your config exist.
 
-2. **Manual mode** (single root):
+```bash
+scaffold structures
+```
 
-   ```bash
-   scaffold scan -r src
-   scaffold scan -r src -o scaffold/src.txt
-   ```
+What it does:
 
-   Options:
+* Loads `.scaffold/config.*`.
+* Determines which structure files are expected:
 
-   * `-r, --root <path>` – directory to scan.
-   * `-o, --out <path>` – output file (otherwise prints to stdout).
-   * `--ignore <patterns...>` – extra globs to ignore (in addition to defaults like `node_modules/**`, `.git/**`, etc.).
+  * **Grouped mode** (`config.groups` defined): each group gets `group.structureFile || `${group.name}.txt``.
+  * **Single-root mode** (no groups): uses `config.structureFile || 'structure.txt'`.
+* For each expected structure file:
+
+  * If it **already exists** → it is left untouched.
+  * If it is **missing** → it is created with a small header comment.
+
+Examples:
+
+```bash
+# With grouped config:
+# groups: [
+#   { name: 'app', root: 'app', structureFile: 'app.txt' },
+#   { name: 'frontend', root: 'resources/js', structureFile: 'frontend.txt' },
+# ]
+scaffold structures
+# => ensures .scaffold/app.txt and .scaffold/frontend.txt exist
+
+# With single-root config:
+# structureFile: 'structure.txt'
+scaffold structures
+# => ensures .scaffold/structure.txt exists
+```
+
+This is useful right after setting up or editing `.scaffold/config.ts` so that all declared structure files are present and ready to edit.
 
 ---
 
@@ -276,8 +335,8 @@ import { runOnce } from '@timeax/scaffold';
 
 await runOnce(process.cwd(), {
   // optional overrides
-  configPath: 'scaffold/config.ts',
-  scaffoldDir: 'scaffold',
+  configPath: '.scaffold/config.ts',
+  scaffoldDir: '.scaffold',
 });
 ```
 
@@ -298,7 +357,7 @@ const results = await scanProjectFromConfig(process.cwd(), {
   groups: ['app', 'frontend'],
 });
 
-// write group structure files to scaffold/
+// write group structure files to .scaffold/
 await writeScannedStructuresFromConfig(process.cwd(), {
   groups: ['app'],
 });
@@ -362,7 +421,9 @@ const config: ScaffoldConfig = {
       name: 'page',
       async getContent(ctx) {
         const name = ctx.targetPath.split('/').pop();
-        return `export default function ${name}() {\n  return <div>${name}</div>;\n}`;
+        return `export default function ${name}() {
+  return <div>${name}</div>;
+}`;
       },
       hooks: {
         preStub: [
@@ -379,7 +440,7 @@ const config: ScaffoldConfig = {
 };
 ```
 
-In `structure.txt`:
+In a structure file:
 
 ```txt
 src/
@@ -420,5 +481,82 @@ Some things this package is intentionally designed to grow into:
 * Stub groups (one logical stub creating multiple files).
 * Built‑in templates for common stacks (Laravel + Inertia, Next.js, etc.).
 * Better diff/dry‑run UX (show what will change without touching disk).
+* Deeper VS Code integration:
+
+  * Tree-aware sorting.
+  * Visual tree editor.
+  * Code actions / quick fixes for common mistakes.
 
 PRs and ideas are welcome ✨
+
+---
+
+## VS Code extension
+
+There is an official VS Code companion extension for `@timeax/scaffold` that makes working with your structure files much nicer.
+
+### Language support
+
+The extension adds a custom language **Scaffold Structure** and:
+
+* Highlights:
+
+  * Directories (lines ending with `/`)
+  * Files
+  * Inline annotations like `@stub:name`, `@include:pattern`, `@exclude:pattern`
+  * Comments using `#` or `//` (full-line and inline)
+* Treats the following files as scaffold structures:
+
+  * `*.tss`
+  * `*.stx`
+  * `structure.txt`
+  * Any `.txt` file inside your `.scaffold/` directory
+
+The syntax rules match the CLI parser:
+
+* Indent is in fixed steps (configurable via `indentStep`).
+* Only directories can have children.
+* `:` is reserved for annotations and not allowed inside path names.
+
+### Editor commands
+
+The extension contributes several commands (available via the Command Palette and context menus when editing a scaffold structure file):
+
+* **Scaffold: Go to file**
+
+  * Reads the path on the current line and opens the corresponding file in your project.
+  * Respects `.scaffold/config.*`:
+
+    * Uses `base`/`root` to resolve paths.
+    * If the current structure file belongs to a `group`, it resolves relative to that group’s `root`.
+  * If the file doesn’t exist, it can prompt to create it and open it immediately.
+
+* **Scaffold: Format structure file**
+
+  * Normalizes line endings and trims trailing whitespace.
+  * Designed to be safe even on partially-invalid files.
+  * Future versions may use the full AST from `@timeax/scaffold` to enforce indentation and ordering.
+
+* **Scaffold: Sort entries**
+
+  * Naive helper that sorts non-comment lines lexicographically while keeping comment/blank lines in place.
+  * Useful for quick cleanups of small structure files.
+
+* **Scaffold: Open config**
+
+  * Opens `.scaffold/config.*` for the current workspace (searching common extensions like `config.ts`, `config.mts`, etc.).
+
+* **Scaffold: Open .scaffold folder**
+
+  * Reveals the `.scaffold/` directory in the VS Code Explorer.
+
+### Live validation (diagnostics)
+
+Whenever you open or edit a scaffold structure file:
+
+* The extension calls `parseStructureText` from `@timeax/scaffold` under the hood.
+* If parsing fails, the error message (e.g. invalid indentation, children under a file, bad path, etc.) is shown as an editor diagnostic (squiggly underline) on the relevant line.
+
+This means your editor and the CLI always agree on what is valid, since they share the same parser and rules.
+
+> The extension is optional, but highly recommended if you edit `*.tss` / `*.stx` or `structure.txt` files frequently.

package/scripts/postpublish.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// scripts/postpublish.mjs
+
+import fs from "node:fs";
+import path from "node:path";
+
+function incrementPatch(version) {
+   const parts = version.split(".");
+
+   if (parts.length !== 3) {
+      throw new Error(`[postpublish] Unsupported version format: "${version}"`);
+   }
+
+   const [majorRaw, minorRaw, patchRaw] = parts;
+   const major = Number(majorRaw);
+   const minor = Number(minorRaw);
+   const patch = Number(patchRaw);
+
+   if (Number.isNaN(major) || Number.isNaN(minor) || Number.isNaN(patch)) {
+      throw new Error(
+         `[postpublish] Version contains non-numeric parts: "${version}"`
+      );
+   }
+
+   const nextPatch = patch + 1;
+   return `${major}.${minor}.${nextPatch}`;
+}
+
+function main() {
+   const pkgPath = path.resolve(process.cwd(), "package.json");
+
+   if (!fs.existsSync(pkgPath)) {
+      console.error("[postpublish] Could not find package.json at", pkgPath);
+      process.exit(1);
+   }
+
+   const raw = fs.readFileSync(pkgPath, "utf8");
+   let pkg;
+
+   try {
+      pkg = JSON.parse(raw);
+   } catch (e) {
+      console.error("[postpublish] Failed to parse package.json:", e);
+      process.exit(1);
+   }
+
+   const currentVersion = pkg.version;
+   if (typeof currentVersion !== "string") {
+      console.error(
+         '[postpublish] package.json does not have a string "version" field.'
+      );
+      process.exit(1);
+   }
+
+   let nextVersion;
+   try {
+      nextVersion = incrementPatch(currentVersion);
+   } catch (e) {
+      console.error(String(e));
+      process.exit(1);
+   }
+
+   pkg.version = nextVersion;
+
+   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+
+   console.log(
+      `[postpublish] Bumped version in package.json: ${currentVersion} → ${nextVersion}`
+   );
+}
+
+main();

package/scripts/prepublish.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// scripts/prepublish.mjs
+
+import { spawnSync } from "node:child_process";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+function run(command, args, options = {}) {
+   const result = spawnSync(command, args, {
+      stdio: "inherit",
+      ...options,
+   });
+
+   if (result.error) {
+      console.error(`[prepublish] Failed to run ${command}:`, result.error);
+      process.exit(1);
+   }
+
+   if (typeof result.status === "number" && result.status !== 0) {
+      process.exit(result.status);
+   }
+
+   return result;
+}
+
+function runCapture(command, args, options = {}) {
+   const result = spawnSync(command, args, {
+      encoding: "utf8",
+      stdio: ["inherit", "pipe", "pipe"],
+      ...options,
+   });
+
+   if (result.error) {
+      throw result.error;
+   }
+
+   return result;
+}
+
+async function main() {
+   // Check if we're in a git repo
+   try {
+      const revParse = runCapture("git", [
+         "rev-parse",
+         "--is-inside-work-tree",
+      ]);
+      if (revParse.status !== 0) {
+         console.log("[prepublish] Not a git repository; skipping git checks.");
+         return;
+      }
+   } catch {
+      console.log("[prepublish] Not a git repository; skipping git checks.");
+      return;
+   }
+
+   // Check for uncommitted changes
+   const status = runCapture("git", ["status", "--porcelain"]);
+   const outputText = status.stdout.trim();
+
+   if (!outputText) {
+      console.log("[prepublish] Working tree clean. Nothing to commit.");
+      return;
+   }
+
+   console.log("[prepublish] You have uncommitted changes:\n");
+   console.log(outputText + "\n");
+
+   const rl = readline.createInterface({ input, output });
+   const message = (
+      await rl.question(
+         "[prepublish] Commit message (leave blank to abort publish): "
+      )
+   ).trim();
+   await rl.close();
+
+   if (!message) {
+      console.error(
+         "[prepublish] No commit message provided. Aborting publish."
+      );
+      process.exit(1);
+   }
+
+   console.log("[prepublish] Staging changes...");
+   run("git", ["add", "."]);
+
+   console.log("[prepublish] Committing...");
+   run("git", ["commit", "-m", message]);
+
+   console.log("[prepublish] Pushing to default remote...");
+   run("git", ["push"]);
+
+   console.log("[prepublish] Git push completed. Proceeding with publish.");
+}
+
+await main();

package/src/cli/main.ts

@@ -5,6 +5,7 @@ import { Command } from 'commander';
 import { runOnce, RunOptions } from '../core/runner';
 import { watchScaffold } from '../core/watcher';
 import {
+  ensureStructureFilesFromConfig,
   scanDirectoryToStructureText,
   writeScannedStructuresFromConfig,
 } from '../core/scan-structure';
@@ -170,6 +171,30 @@ async function handleInitCommand(
   );
 }
 
+
+async function handleStructuresCommand(
+  cwd: string,
+  baseOpts: BaseCliOptions,
+) {
+  const logger = createCliLogger(baseOpts);
+
+  logger.info('Ensuring structure files declared in config exist...');
+
+  const { created, existing } = await ensureStructureFilesFromConfig(cwd, {
+    scaffoldDirOverride: baseOpts.dir,
+  });
+
+  if (created.length === 0) {
+    logger.info('All structure files already exist. Nothing to do.');
+  } else {
+    for (const filePath of created) {
+      logger.info(`Created structure file: ${filePath}`);
+    }
+  }
+
+  existing.forEach((p) => logger.debug(`Structure file already exists: ${p}`));
+}
+
 async function main() {
   const cwd = process.cwd();
 
@@ -234,9 +259,22 @@ async function main() {
     await handleRunCommand(cwd, opts);
   });
 
+  interface StructuresCliOptions { }
+
+  program
+    .command('structures')
+    .description(
+      'Create missing structure files specified in the config (does not overwrite existing files)',
+    )
+    .action(async (_opts: StructuresCliOptions, cmd: Command) => {
+      const baseOpts = cmd.parent?.opts<BaseCliOptions>() ?? {};
+      await handleStructuresCommand(cwd, baseOpts);
+    });
+
   await program.parseAsync(process.argv);
 }
 
+
 // Run and handle errors
 main().catch((err) => {
   defaultLogger.error(err);

package/src/core/config-loader.ts

@@ -7,12 +7,13 @@ import crypto from 'crypto';
 import { pathToFileURL } from 'url';
 import { transform } from 'esbuild';
 
-import type { ScaffoldConfig } from '../schema';
+import { SCAFFOLD_ROOT_DIR, type ScaffoldConfig } from '../schema';
 import { defaultLogger } from '../util/logger';
 import { ensureDirSync } from '../util/fs-utils';
 
 const logger = defaultLogger.child('[config]');
 
+
 export interface LoadScaffoldConfigOptions {
    /**
     * Optional explicit scaffold directory path (absolute or relative to cwd).
@@ -68,7 +69,7 @@ export async function loadScaffoldConfig(
    // First pass: figure out an initial scaffold dir just to locate config.*
    const initialScaffoldDir = options.scaffoldDir
       ? path.resolve(absCwd, options.scaffoldDir)
-      : path.join(absCwd, 'scaffold');
+      : path.join(absCwd, SCAFFOLD_ROOT_DIR);
 
    const configPath =
       options.configPath ?? resolveConfigPath(initialScaffoldDir);
@@ -85,7 +86,7 @@ export async function loadScaffoldConfig(
    // Final scaffoldDir (can still be overridden by CLI)
    const scaffoldDir = options.scaffoldDir
       ? path.resolve(absCwd, options.scaffoldDir)
-      : path.join(configRoot, 'scaffold');
+      : path.join(configRoot, SCAFFOLD_ROOT_DIR);
 
    // projectRoot (base) is relative to configRoot
    const baseRoot = config.base

package/src/core/init-scaffold.ts

@@ -4,6 +4,7 @@ import fs from 'fs';
 import path from 'path';
 import { ensureDirSync } from '../util/fs-utils';
 import { defaultLogger } from '../util/logger';
+import { SCAFFOLD_ROOT_DIR } from '../schema';
 
 const logger = defaultLogger.child('[init]');
 
@@ -52,7 +53,10 @@ const config: ScaffoldConfig = {
   //   base: 'src',        // apply to <root>/src
   //   base: '..',         // apply to parent of <root>
   // base: '.',
-
+  
+  // Number of spaces per indent level in structure files (default: 2).
+  // indentStep: 2,
+  
   // Cache file path, relative to base.
   // cacheFile: '.scaffold-cache.json',
 
@@ -85,7 +89,8 @@ const config: ScaffoldConfig = {
 export default config;
 `;
 
-const DEFAULT_STRUCTURE_TXT = `# scaffold/structure.txt
+
+const DEFAULT_STRUCTURE_TXT = `# ${SCAFFOLD_ROOT_DIR}/structure.txt
 # Example structure definition.
 # - Indent with 2 spaces per level
 # - Directories must end with "/"
@@ -113,7 +118,7 @@ export async function initScaffold(
    structurePath: string;
    created: { config: boolean; structure: boolean };
 }> {
-   const scaffoldDirRel = options.scaffoldDir ?? 'scaffold';
+   const scaffoldDirRel = options.scaffoldDir ?? SCAFFOLD_ROOT_DIR;
    const scaffoldDirAbs = path.resolve(cwd, scaffoldDirRel);
    const configFileName = options.configFileName ?? 'config.ts';
    const structureFileName = options.structureFileName ?? 'structure.txt';