@oamm/textor 1.0.0

package/README.md

@@ -0,0 +1,399 @@
+# Textor
+
+A safe, deterministic scaffolding and refactoring CLI tool for Astro + modern frontend projects.
+
+Textor enforces strict separation of concerns:
+- **Pages** = Thin routing adapters
+- **Features** = Self-contained implementation modules
+- **Components** = Reusable UI primitives
+
+The tool is designed to be production-grade, principal-engineer approved, and optimized for large teams and long-lived codebases.
+
+## 🔒 Core Principles
+
+1.  **Explicit over implicit** — No magic behavior.
+2.  **Safe by default** — Never delete or overwrite hand-written code.
+3.  **Configurable over hardcoded** — Everything driven by configuration.
+4.  **Reversible operations** — Add, move, and remove operations are always supported.
+5.  **Deterministic output** — Same input always produces the same structure.
+
+## 🚀 Installation
+
+```bash
+# In your Astro project
+pnpm add -D @oamm/textor
+
+# Initialize configuration
+pnpm textor init
+```
+
+This creates .textor/config.json with default settings and initializes the state tracker.
+
+## 🏗️ Scaffolding Presets
+
+Control structural complexity using presets. Presets apply to both add-section and create-component.
+
+-   **minimal**: Lean defaults, minimal folders. Ideal for simple components and features.
+-   **standard**: Balanced structure. Includes hooks, tests, and types by default.
+-   **senior**: Full enterprise-grade layout including API, services, schemas, and documentation.
+
+Select a preset via the --preset flag:
+```bash
+pnpm textor add-section /users users/catalog --preset senior
+```
+
+## 🗺️ Routing Mode
+
+Textor supports explicit routing strategies to avoid ambiguity in Astro projects.
+
+-   **flat**: /users → src/pages/users.astro (Default)
+-   **nested**: /users → src/pages/users/index.astro
+
+Configure this in .textor/config.json:
+```json
+{
+  "routing": {
+    "mode": "nested",
+    "indexFile": "index.astro"
+  }
+}
+```
+
+Textor supports multiple frameworks (React, Astro). By default, components are created as React components (`.tsx`), while features and pages are Astro components (`.astro`).
+
+Configure this in `.textor/config.json`:
+```json
+{
+  "components": {
+    "framework": "react"
+  },
+  "features": {
+    "framework": "astro"
+  }
+}
+```
+
+## 📦 Feature Entry Strategy
+
+Avoid filename collisions for feature entry files.
+
+-   **pascal**: src/features/users/catalog/UsersCatalog.astro (Default)
+-   **index**: src/features/users/catalog/index.astro
+
+Configure this in .textor/config.json:
+```json
+{
+  "features": {
+    "entry": "pascal"
+  }
+}
+```
+
+## 🛡️ Safety & File Tracking
+
+Textor uses a multi-layered safety approach to protect your codebase.
+
+### 1. File Signatures
+Every file generated by Textor includes a signature (e.g., <!-- @generated by Textor -->). Textor will refuse to delete or move any file missing this signature unless --force is used.
+
+### 2. State Tracking & Hashing
+Textor maintains a .textor/state.json file that tracks:
+- File paths and kind (route, feature, component)
+- Templates used
+- **Content hashes**
+- Creation timestamps
+
+### 3. Integrity Verification
+Safe deletion and moves require:
+1.  Valid Textor signature in the file.
+2.  Presence of the file in the state.
+3.  **Hash match** (verifying the file hasn't been manually edited).
+
+If you have manually edited a Textor-generated file and wish to remove or move it, use --accept-changes or --force.
+
+## 🛠️ Commands
+
+### add-section
+Create a route + feature binding.
+
+```bash
+pnpm textor add-section <route> <featurePath> [options]
+```
+
+**Options:**
+- --preset <name>: scaffolding preset (minimal, standard, senior)
+- --layout <name>: Layout component name (use "none" for no layout)
+- --name <name>: Custom name for easier state lookup
+- --endpoint: Create an API endpoint (.ts) instead of an Astro page
+- --dry-run: Preview changes without writing to disk
+
+### create-component
+Create reusable UI components.
+
+```bash
+pnpm textor create-component <ComponentName> [options]
+```
+
+**Options:**
+- --preset <name>: scaffolding preset (minimal, standard, senior)
+- --dry-run: Preview changes without writing to disk
+
+### move-section
+Move and rename sections safely. Textor performs **deep renaming**: if the feature name changes, all internal files and component signatures are updated automatically.
+
+```bash
+# Using state lookup
+pnpm textor move-section /old /new
+```
+
+### remove-section / remove-component
+Safely remove Textor-managed modules.
+
+### list-sections
+List all Textor-managed modules, including their architectural capabilities (API, Hooks, etc.).
+
+### status
+Show drift between state and disk. This is a read-only command used to build trust and identify manual changes or missing files.
+
+```bash
+pnpm textor status
+```
+
+**Categories:**
+- **SYNCED**: File content matches state exactly.
+- **MODIFIED**: File exists but content differs from state hash.
+- **MISSING**: File is registered in state but missing on disk.
+- **UNTRACKED**: File has a Textor signature but is not in state.
+- **ORPHANED**: File is in a managed directory but has no Textor signature and is not in state.
+
+### validate-state
+Validate that the state file matches the project files.
+
+### sync
+Synchronize the state with the actual files in managed directories. This is useful for including existing files into Textor's state or updating hashes after manual edits.
+
+```bash
+pnpm textor sync [options]
+```
+
+**Options:**
+- `--include-all`: Include all files in managed directories, even without the Textor signature.
+- `--force`: Update hashes for modified files even if they don't have the Textor signature.
+- `--dry-run`: Preview what would be synchronized without making changes.
+
+### adopt
+Adopt untracked files into Textor's state and add the Textor signature to them. This is the recommended way to bring manually created components or sections under Textor's management.
+
+```bash
+pnpm textor adopt <path-or-identifier> [options]
+```
+
+**Options:**
+- `--all`: Scan all managed directories for untracked files and adopt them.
+- `--dry-run`: Preview which files would be adopted and modified.
+
+**Examples:**
+```bash
+# Adopt a specific component directory
+pnpm textor adopt src/components/MyNewButton
+
+# Adopt a section by its route
+pnpm textor adopt /users
+
+# Adopt all untracked files in the project
+pnpm textor adopt --all
+```
+
+## 🏗️ Technical Architecture
+
+Textor is designed with enterprise-grade robustness, moving beyond simple scaffolding to provide a reliable refactoring engine.
+
+### 1. Atomic State Operations
+State updates to `.textor/state.json` are atomic. Textor writes to a temporary file (`state.json.tmp`) and performs a cross-platform rename to the final destination. This prevents state corruption during crashes or interrupted operations.
+
+### 2. Robust Hashing & Normalization
+Textor uses SHA-256 for file integrity. It supports multiple normalization strategies:
+- **normalizeEOL** (Default): Converts `\r\n` to `\n` before hashing. Ensures Git "autocrlf" settings don't trigger false alerts.
+- **stripGeneratedRegions**: Hashes only the content within `@generated by Textor:begin` and `@generated by Textor:end` markers. This allows developers to add hand-written code outside these regions without breaking Textor's integrity checks.
+- **none**: Strict hashing of the entire file.
+
+### 3. Explicit Ownership Model
+Every file in the state has an **owner**. 
+- A **Section** owns its route adapter and its associated feature directory.
+- A **Component** owns its specific component directory.
+Textor enforces ownership boundaries to prevent accidental deletion of shared resources and to ensure deep refactors only touch relevant files. Use `--force` to override ownership checks.
+
+### 4. Kind Inference & Rules
+Textor can infer the "kind" of a file (e.g., `route`, `feature`, `component-file`) during synchronization. You can define custom rules in `.textor/config.json`:
+```json
+{
+  "kindRules": [
+    { "match": "src/features/custom/**", "kind": "custom-logic" },
+    { "match": "**/special.ts", "kind": "special-file" }
+  ]
+}
+```
+
+### 5. Git Safety Integration
+Textor integrates with Git to provide a "safety net":
+- `requireCleanRepo`: When enabled, Textor refuses to perform destructive operations (remove/move) if the repository has uncommitted changes.
+- `stageChanges`: When enabled, Textor automatically stages (`git add`) all created or modified files after a successful command.
+
+### 6. Scoped & Repo-wide Import Rewriting
+When moving or renaming sections, Textor performs scoped AST-like updates:
+- **Scope**: Updates imports in Textor-managed files and route adapters by default.
+- **Repo-wide**: Use the `--scan` flag to scan the entire repository for imports that need to be updated.
+- **Exclusions**: String literals, markdown documentation (unless registered), and complex dynamic imports are preserved to avoid breaking hand-written logic.
+
+---
+
+## ⚙️ Configuration
+
+The .textor/config.json file allows full control over the tool's behavior.
+
+```json
+{
+  "paths": {
+    "pages": "src/pages",
+    "features": "src/features",
+    "components": "src/components",
+    "layouts": "src/layouts"
+  },
+  "routing": {
+    "mode": "flat",
+    "indexFile": "index.astro"
+  },
+  "importAliases": {
+  },
+  "naming": {
+    "routeExtension": ".astro",
+    "featureExtension": ".astro",
+    "componentExtension": ".tsx",
+    "hookExtension": ".ts",
+    "testExtension": ".test.tsx"
+  },
+  "signatures": {
+    "astro": "<!-- @generated by Textor -->",
+    "typescript": "// @generated by Textor",
+    "javascript": "// @generated by Textor",
+    "tsx": "// @generated by Textor"
+  },
+  "features": {
+    "framework": "astro",
+    "entry": "pascal",
+    "createSubComponentsDir": true,
+    "createScriptsDir": true,
+    "scriptsIndexFile": "scripts/index.ts",
+    "createApi": false,
+    "createServices": false,
+    "createSchemas": false,
+    "createHooks": false,
+    "createContext": false,
+    "createTests": false,
+    "createTypes": false,
+    "createReadme": false,
+    "createStories": false,
+    "createIndex": false
+  },
+  "components": {
+    "framework": "react",
+    "createSubComponentsDir": true,
+    "createContext": true,
+    "createHook": true,
+    "createTests": true,
+    "createConfig": true,
+    "createConstants": true,
+    "createTypes": true,
+    "createApi": false,
+    "createServices": false,
+    "createSchemas": false,
+    "createReadme": false,
+    "createStories": false
+  },
+  "formatting": {
+    "tool": "none"
+  },
+  "hashing": {
+    "normalization": "normalizeEOL"
+  },
+  "git": {
+    "requireCleanRepo": false,
+    "stageChanges": false
+  },
+  "defaultPreset": "standard",
+  "presets": {
+    "minimal": {
+      "features": { "createSubComponentsDir": false, "createScriptsDir": false },
+      "components": {
+        "createSubComponentsDir": false,
+        "createContext": false,
+        "createHook": false,
+        "createTests": false,
+        "createConfig": false,
+        "createConstants": false,
+        "createTypes": false
+      }
+    },
+    "standard": {
+      "features": { "createSubComponentsDir": true, "createScriptsDir": true },
+      "components": {
+        "createSubComponentsDir": true,
+        "createContext": true,
+        "createHook": true,
+        "createTests": true,
+        "createConfig": true,
+        "createConstants": true,
+        "createTypes": true
+      }
+    },
+    "senior": {
+      "features": {
+        "createSubComponentsDir": true,
+        "createScriptsDir": true,
+        "createApi": true,
+        "createServices": true,
+        "createSchemas": true,
+        "createHooks": true,
+        "createContext": true,
+        "createTests": true,
+        "createTypes": true,
+        "createReadme": true,
+        "createStories": true,
+        "createIndex": true
+      },
+      "components": {
+        "createSubComponentsDir": true,
+        "createContext": true,
+        "createHook": true,
+        "createTests": true,
+        "createConfig": true,
+        "createConstants": true,
+        "createTypes": true,
+        "createApi": true,
+        "createServices": true,
+        "createSchemas": true,
+        "createReadme": true,
+        "createStories": true
+      }
+    }
+  }
+}
+```
+*Supported formatting tools: prettier, biome, none.*
+
+## 📝 Template Overrides
+
+Customize generated code by placing templates in .textor/templates/. Supported templates:
+- route.astro
+- feature.astro
+- component.astro
+- hook.ts
+- context.tsx
+- test.tsx
+- index.ts
+
+Templates use {{variable}} syntax for placeholder replacement.
+
+---
+
+Textor is designed to be a tool you trust to refactor a 3-year-old production codebase without fear.

package/dist/bin/textor.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};