@oamm/textor 1.0.2 → 1.0.4

package/README.md

@@ -89,6 +89,42 @@ Configure this in .textor/config.json:
 }
 ```
 
+## File Naming Patterns
+
+You can override generated file names for feature and component sub-files (api, services, hooks, tests, etc.) using simple patterns. Patterns support `{{componentName}}`, `{{hookName}}`, `{{hookExtension}}`, `{{testExtension}}`, `{{componentExtension}}`, and `{{featureExtension}}`.
+
+Example:
+```json
+{
+  "filePatterns": {
+    "features": {
+      "api": "{{componentName}}.route.ts"
+    },
+    "components": {
+      "api": "{{componentName}}.route.ts"
+    }
+  }
+}
+```
+
+More examples:
+```json
+{
+  "filePatterns": {
+    "features": {
+      "hook": "use{{componentName}}.ts",
+      "test": "{{componentName}}.spec{{testExtension}}",
+      "readme": "{{componentName}}.md"
+    },
+    "components": {
+      "api": "{{componentName}}.route{{testExtension}}",
+      "services": "{{componentName}}.service{{hookExtension}}",
+      "stories": "{{componentName}}.stories.tsx"
+    }
+  }
+}
+```
+
 ## 🛡️ Safety & File Tracking
 
 Textor uses a multi-layered safety approach to protect your codebase.
@@ -223,6 +259,26 @@ pnpm textor adopt /users
 pnpm textor adopt --all
 ```
 
+### upgrade-config
+Upgrade `.textor/config.json` to the latest schema version without recreating it.
+
+```bash
+pnpm textor upgrade-config
+```
+
+**Options:**
+- `--dry-run`: Print the upgraded config without writing it.
+
+### normalize-state
+Normalize `.textor/state.json` to use project-relative paths (helpful when moving between machines).
+
+```bash
+pnpm textor normalize-state
+```
+
+**Options:**
+- `--dry-run`: Print the normalized state without writing it.
+
 ## 🏗️ Technical Architecture
 
 Textor is designed with enterprise-grade robustness, moving beyond simple scaffolding to provide a reliable refactoring engine.
@@ -269,9 +325,11 @@ When moving or renaming sections, Textor performs scoped AST-like updates:
 ## ⚙️ Configuration
 
 The .textor/config.json file allows full control over the tool's behavior.
+`configVersion` tracks schema changes and is updated by `textor upgrade-config`.
 
 ```json
 {
+  "configVersion": 2,
   "paths": {
     "pages": "src/pages",
     "features": "src/features",
@@ -402,16 +460,79 @@ The .textor/config.json file allows full control over the tool's behavior.
 
 ## 📝 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
+You can customize the code generated by Textor by providing your own templates. Textor looks for override files in the `.textor/templates/` directory at your project root.
+
+### How to use Template Overrides
+
+1.  Create the `.textor/templates/` directory if it doesn't exist.
+2.  Create a file named according to the table below (e.g., `feature.astro` or `component.tsx`).
+3.  Use `{{variable}}` placeholders in your template. Textor will automatically replace them when generating files.
+
+### Supported Templates
+
+| Template Name | File to create in `.textor/templates/` | Available Variables |
+| :--- | :--- | :--- |
+| **Route** | `route.astro` | `{{layoutName}}`, `{{layoutImportPath}}`, `{{featureImportPath}}`, `{{featureComponentName}}` |
+| **Feature** | `feature.astro` or `feature.tsx` | `{{componentName}}`, `{{scriptImportPath}}` |
+| **Component** | `component.astro` or `component.tsx` | `{{componentName}}` |
+| **Hook** | `hook.ts` | `{{componentName}}`, `{{hookName}}` |
+| **Context** | `context.tsx` | `{{componentName}}` |
+| **Test** | `test.tsx` | `{{componentName}}`, `{{componentPath}}` |
+| **Index** | `index.ts` | `{{componentName}}`, `{{componentExtension}}` |
+| **Types** | `types.ts` | `{{componentName}}` |
+| **API** | `api.ts` | `{{componentName}}` |
+| **Endpoint** | `endpoint.ts` | `{{componentName}}` |
+| **Service** | `service.ts` | `{{componentName}}` |
+| **Schema** | `schema.ts` | `{{componentName}}` |
+| **Readme** | `readme.md` | `{{componentName}}` |
+| **Stories** | `stories.tsx` | `{{componentName}}`, `{{componentPath}}` |
+| **Config** | `config.ts` | `{{componentName}}` |
+| **Constants** | `constants.ts` | `{{componentName}}` |
+| **Scripts Index**| `scripts-index.ts` | (none) |
+
+> **Note:** For `feature` and `component` templates, use the extension that matches your configured framework (`.astro` for Astro, `.tsx` for React). Other templates have fixed extensions for the override file, regardless of your project's configuration.
+
+### Variables Description
+
+- `{{componentName}}`: The PascalCase name of the feature or component (e.g., `UserCatalog`).
+- `{{hookName}}`: The camelCase name of the generated hook (e.g., `useUserCatalog`).
+- `{{componentPath}}`: Relative path to the component file (useful for imports in tests or stories).
+- `{{featureComponentName}}`: The name of the feature component as imported in a route.
+- `{{featureImportPath}}`: The import path for the feature component.
+- `{{layoutName}}`: The name of the layout component being used.
+- `{{layoutImportPath}}`: The import path for the layout component.
+- `{{scriptImportPath}}`: Relative path to the client-side script entry point.
+- `{{componentExtension}}`: The file extension of the component (e.g., `.astro` or `.tsx`).
+
+### Example: Custom Feature Template (`.textor/templates/feature.astro`)
+
+```astro
+---
+/**
+ * @generated by Textor
+ * Feature: {{componentName}}
+ */
+
+interface Props {
+  title?: string;
+}
+
+const { title = "{{componentName}}" } = Astro.props;
+---
 
-Templates use {{variable}} syntax for placeholder replacement.
+<section class="feature-{{componentName}}">
+  <h2>{title}</h2>
+  <slot />
+</section>
+
+<script src="{{scriptImportPath}}"></script>
+
+<style>
+  .feature-{{componentName}} {
+    padding: 2rem;
+  }
+</style>
+```
 
 ---