Maddex CLI

Maddex CLI fetches remote Caspian-ready Python UI components from the Maddex registry and writes them into your project. It also bootstraps a few project defaults and keeps Maddex metadata in sync for both human and AI-assisted workflows.

What the CLI does

• Installs one or more remote components with maddex add <name...>.
• Supports both multi-file components and legacy single-file component payloads.
• Prompts interactively when you run maddex add without component names.
• Installs the full remote catalogue with maddex add --all.
• Refreshes already installed Python components with maddex update.
• Bootstraps default icons, Tailwind CSS, and the tw-animate-css package when needed.
• Writes a Maddex manifest into maddex.json, refreshes the managed AI context block in .github/instructions/maddex.instructions.md, and keeps .github/copilot-instructions.md available as a stable top-level pointer file.

Supported commands

The CLI currently supports only two commands:

maddex add [--all] [--force] [components...]
maddex update

Examples:

maddex add Button
maddex add Button Card
maddex add
maddex add --all
maddex add --force Button
maddex update

Notes:

• add with no component names opens an interactive text prompt.
• --all is only meaningful with add.
• --force is only parsed for add.
• update always refreshes installed components with overwrite behavior.

First-run and housekeeping behavior

On every CLI run, Maddex first verifies that the current working directory is a Caspian project by checking for caspian.config.json in the project root. After that check passes, it loads maddex.json and creates it if it does not exist.

During normal execution, the CLI also performs these housekeeping steps:

1. If iconsInstalled is false, it installs ppicons globally and runs npx ppicons add ... for a default icon set.
2. It ensures tw-animate-css exists in the current project's dependencies or devDependencies.
3. It copies the bundled globals.css into src/app/globals.css.
4. After a successful install or refresh flow, it writes Maddex manifest data back into maddex.json, updates the managed instruction block in .github/instructions/maddex.instructions.md, and creates .github/copilot-instructions.md when missing without rewriting existing manual content there.

On the first add run, if you are not using --all, Maddex prepends these core components before your requested names:

• Slot
• Portal
• utils

Overwrite behavior is also different on first run:

• First run: bundled globals.css is copied with overwrite enabled.
• Later runs: globals.css is copied only when missing.
• Component files are overwritten only when --force is passed to add, or when update is used.

Generated files

By default, Maddex writes Python components into:

src/lib/maddex

Component payloads can contain one file or several files. For example:

src/lib/maddex/
  Button.py
  Button.html

Maddex may also create or update these files:

• maddex.json
• src/app/globals.css
• .github/instructions/maddex.instructions.md
• .github/copilot-instructions.md

Important details:

• update discovers installed components by scanning only .py files in outputDir.
• __init__.py is ignored during update scans.
• Sidecar files such as .html files are written during component generation, but they are not used to discover installed components.
• Manual content outside the Maddex-managed block in .github/instructions/maddex.instructions.md is preserved.
• .github/copilot-instructions.md is kept as a stable top-level file and is not used as the Maddex-managed block target.

First-party CRUD pattern

For Maddex and Caspian CRUD screens, the default composition pattern is:

• Let index.py and index.html own the list shell, search, pagination, lookup data, and dialog state.
• Use one CreateUpdateDialog composition component for both create and update flows, built with Maddex Dialog primitives.
• Drive create versus update from selectedItem or selectedItem.id, and map that value into local form state when the dialog opens.
• Keep create and update mutations in one save_* RPC next to that dialog component.
• After a successful save, update the parent items collection in place and close the dialog before falling back to a full refetch.
• Use a dedicated DeleteDialog confirmation component built with Maddex AlertDialog primitives for deletes.
• Keep the delete mutation in a delete_* RPC next to the delete dialog and remove the deleted record from the parent items collection after confirmation.
• Pass openDialog, setOpenDialog, selectedItem, items, and setItems as composition props instead of introducing ad-hoc global state for simple CRUD flows.
• Treat this as the first pattern AI should reach for when generating Maddex CRUD screens unless the host repo already has a stronger local convention.

Configuration

When maddex.json does not exist, Maddex creates it with this default shape:

{
  "style": "default",
  "force": false,
  "outputDir": "src/lib/maddex",
  "iconsInstalled": false,
  "tailwind": {
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "pythonPath": "src/lib/maddex",
  "iconLibrary": "ppicons"
}

After a successful Maddex refresh, the CLI also writes a manifest object into maddex.json that records:

• installed component inventory
• component directory
• Python module path hints
• registry API metadata
• Tailwind CSS metadata
• icon library metadata

What the current runtime actually uses

The current implementation actively uses these config values:

| Field | Current behavior | | ---------------- | ---------------------------------------------------------------------------------------------- | | outputDir | Controls where component files are written and where update scans for installed .py files. | | iconsInstalled | Controls whether the icon bootstrap runs again. | | pythonPath | Used when building manifest and AI context metadata. | | iconLibrary | Recorded in the generated manifest and managed AI context content. | | tailwind.css | Recorded in generated metadata. |

Fields that are currently persisted but do not directly change CLI runtime behavior:

• style
• force
• tailwind.baseColor
• tailwind.cssVariables
• tailwind.prefix

Current implementation note:

• The bundled CSS copy step always writes to src/app/globals.css, even if tailwind.css in maddex.json points somewhere else.
• The CLI overwrite switch for component files is the --force command-line flag, not the persisted force field in maddex.json.

Remote registry API

Maddex fetches components from:

• GET https://maddex.tsnc.tech/cli?component=all
• GET https://maddex.tsnc.tech/cli?component=<component-name>

The component=all endpoint returns a JSON array of component names.

Single-component responses can use either of these shapes.

Multi-file payload:

{
  "name": "Button",
  "files": [
    {
      "name": "Button.py",
      "content": "class Button:\n    ...generated Python source..."
    },
    {
      "name": "Button.html",
      "content": "<button>...generated template...</button>"
    }
  ]
}

Legacy single-file payload:

{
  "name": "Button",
  "content": "...generated Python source..."
}

If the API returns an error status or no usable files or content, Maddex fails the current install for that component.

Installation and local development

This repository currently exposes the executable name maddex through the package bin field.

To work with the CLI from this repository checkout:

npm install
npm run build
node dist/index.js add Button

If you want the maddex command available globally while developing locally:

npm install
npm run build
npm link
maddex add Button

If you publish this package under your own npm package name, install that package and invoke the maddex executable it exposes.

Requirements

• Node.js 18 or newer is recommended.
• npm must be available because the CLI installs missing packages and the icon bootstrap depends on npx.
• The target project must be a Caspian project root and include caspian.config.json.
• The target project should contain package.json if you want Maddex to auto-install tw-animate-css.
• The environment must allow npm install -g ppicons the first time icon bootstrap runs.

Contributor workflow

Useful commands in this repository:

npm test
npm run build

The build step compiles TypeScript, copies bundled CSS assets into dist, and minifies the final output.

Troubleshooting

• No components found to update. means the configured outputDir does not currently contain any installable .py component files.
• If icon bootstrap fails, verify that global npm installs are allowed and that npx ppicons can run in your environment.
• If a component is skipped during add, check whether the file already exists and rerun with --force if overwrite is intended.
• If your project uses a Tailwind CSS file outside src/app/globals.css, note that the current bootstrap copier still targets src/app/globals.css.

License

MIT

Author

Jefferson Abraham Omier [email protected]

Homepage: https://maddex.tsnc.tech/ Repository: https://github.com/TheSteelNinjaCode/maddex.git