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

# 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:

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:

{
  "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:

{
  "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:

{
  "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., ). 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.

pnpm textor add-section <route> <featurePath> [options]

Options:

• --preset : scaffolding preset (minimal, standard, senior)
• --layout : Layout component name (use "none" for no layout)
• --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.

pnpm textor create-component <ComponentName> [options]

Options:

• --preset : 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.

# 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.

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.

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.

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:

# 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:

{
  "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.

{
  "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.