@aliens-syndicate/cli 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.es-ES.md +53 -10
  2. package/README.md +53 -10
  3. package/README.pt-BR.md +53 -10
  4. package/README.zh-CN.md +53 -10
  5. package/package.json +6 -1
  6. package/tools/build.mjs +372 -36
  7. package/tools/cache.mjs +41 -0
  8. package/tools/cli-shared.mjs +237 -0
  9. package/tools/cli.mjs +145 -48
  10. package/tools/create.mjs +207 -78
  11. package/tools/doctor.mjs +139 -0
  12. package/tools/generate.mjs +175 -0
  13. package/tools/icon-docs.mjs +132 -0
  14. package/tools/project-layout.mjs +3 -3
  15. package/tools/runtime.mjs +216 -8
  16. package/tools/serve.mjs +152 -0
  17. package/tools/starter/ai/agents/codingbot.agent +5 -0
  18. package/tools/starter/ai/rules/architecture.rule +12 -0
  19. package/tools/starter/ai/skills/create-element.skill +7 -0
  20. package/tools/starter/app/elements/molecules/kit-card-link/kit-card-link.markup +0 -2
  21. package/tools/starter/app/pages/kit-overview/kit-overview.markup +6 -6
  22. package/tools/starter/app/pages/style-guide/style-guide.style +57 -57
  23. package/tools/starter/styles/components/alerts.style +6 -5
  24. package/tools/starter/styles/components/badges.style +6 -5
  25. package/tools/starter/styles/components/borders.style +2 -1
  26. package/tools/starter/styles/components/buttons.style +14 -13
  27. package/tools/starter/styles/components/cards.style +1 -1
  28. package/tools/starter/styles/components/feedback.style +3 -2
  29. package/tools/starter/styles/components/forms.style +5 -4
  30. package/tools/starter/styles/components/tables.style +4 -3
  31. package/tools/starter/styles/components/typography.style +6 -5
  32. package/tools/starter/styles/generic/ui-base.style +1 -1
  33. package/tools/starter/styles/objects/ui-layout.style +1 -1
  34. package/tools/style-docs.mjs +274 -0
  35. package/tools/update.mjs +110 -0
  36. package/tools/vscode-space/package.json +5 -8
  37. package/tools/vscode-space/space.tmLanguage.json +1 -1
  38. package/tools/vscode-space/syntax.cjs +103 -62
  39. package/tools/watch.mjs +48 -0
package/README.es-ES.md CHANGED
@@ -12,14 +12,28 @@ cd mi-proyecto
12
12
  node tools/build.mjs
13
13
  ```
14
14
 
15
- El mismo generador está publicado en npm como `@aliens-syndicate/cli` y funciona sin clonar el repositorio. El comando `aliens build` ejecuta el `tools/build.mjs` del proyecto en el que estás.
15
+ El mismo generador está publicado en npm como `@aliens-syndicate/cli` y funciona sin clonar el repositorio. Instálalo una vez con `npm install -g @aliens-syndicate/cli`; `aliens new` pregunta qué extensiones usar y ejecuta `npm install`. Los comentarios que empiezan con `#AGENT` son directivas solo para agentes de IA: el build los lista, con archivo y línea, en `directives:` de `ai/.map`.
16
16
 
17
17
  ```sh
18
- npx @aliens-syndicate/cli create mi-proyecto
18
+ npm install -g @aliens-syndicate/cli
19
+ aliens new mi-proyecto
19
20
  cd mi-proyecto
20
- npx @aliens-syndicate/cli build
21
+ aliens run
21
22
  ```
22
23
 
24
+ | Comando | Qué hace |
25
+ | --- | --- |
26
+ | `aliens new <nombre>` (`n`) | Crea un proyecto y pregunta qué extensiones instalar. `--yes`, `--no-style`, `--no-icons`, `--no-elements` y `--skip-install` saltan las preguntas. |
27
+ | `aliens run` | Hace el build, sirve en http://localhost:5151 y rehace el build y recarga el navegador con cada archivo guardado. `--port <número>` o `serve: port:` en `.config` cambia el puerto. `aliens watch` es un atajo. |
28
+ | `aliens build` | Ejecuta el `tools/build.mjs` del proyecto y genera `dist/` y `ai/.map`. |
29
+ | `aliens generate <tipo> <nombre>` (`g`) | Crea archivos Space. `aliens g element molecules/card` escribe `.markup`, `.logic`, `.style` y `.test`; sin el nivel, la CLI pregunta. Los archivos existentes se conservan y solo se crean los que faltan. Tipos: element (`e`), page (`p`), service (`s`), directive (`d`), interface (`i`), model (`m`), validator (`v`), route (`r`), api, animation, enum, error, guard, interceptor, mock, pipe, storage, agent, rule, skill. `--dry-run` no escribe nada. |
30
+ | `aliens doctor` | Revisa Node.js, npm, la versión de la CLI, `.config`, los paquetes, el puerto y el build, con la corrección de cada problema. |
31
+ | `aliens update` | Actualiza los paquetes `@aliens-syndicate` del proyecto y copia el `tools/` de la CLI instalada. `--dry-run` lista los cambios. |
32
+ | `aliens cache` | Borra `dist/` y las cachés de las herramientas. |
33
+ | `aliens version` | Muestra las versiones de la CLI, Node.js, el sistema y los paquetes. `aliens --version` muestra solo el número. |
34
+
35
+ El comentario al inicio de `.config` lista los mismos comandos, y la página **Instalación** del sitio (`#installation`) los explica paso a paso.
36
+
23
37
  Para publicar una nueva versión, actualiza `version` en `package.json` y ejecuta `npm publish` en la raíz, con la cuenta `aliens-syndicate` conectada en npm.
24
38
 
25
39
  El generador crea la Home en `project/app/pages/home/`, los cuatro niveles de Elements y las carpetas de los tipos de archivo de la aplicación. Los ejemplos comentados del catálogo de héroes vienen de la base del motor en `tools/starter/`, independientemente de la aplicación que tengas abierta. El Element `hero-card` reúne `.markup`, `.logic`, `.style` y `.test` en `project/app/elements/molecules/hero-card/`. Las carpetas `agents/`, `rules/` y `skills/` están en `ai/`.
@@ -107,23 +121,28 @@ Escribe el nombre sin `#` ni `.`. El build genera `[id="nombre"]` para un `id` y
107
121
  ```text
108
122
  Style Counter
109
123
  counter-button
110
- border: 1px solid var(--line-strong)
124
+ flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
125
+ hover:border-(--accent-stroke) max-md:w-full
111
126
  counter-button_increase
112
- background: var(--primary)
113
- counter-button:hover
114
- border-color: var(--accent-stroke)
127
+ bg-(--primary) text-(--primary-ink)
115
128
  ```
116
129
 
130
+ Dentro de un selector, una línea escrita como `propiedad: valor` es una declaración CSS. Por defecto, `.style` acepta solo CSS normal. Las utilidades son opcionales y viven en su propio paquete: instala `@aliens-syndicate/style` y decláralo en `.config` bajo `style:` con `from: @aliens-syndicate/style`. Sin él, una línea de utilidades detiene el build y explica cómo añadir el paquete. Con él, cualquier otra línea enumera utilidades con los nombres popularizados por frameworks de CSS existentes: `flex`, `gap-4`, `rounded-lg`, `text-sm`. Variantes como `md:`, `max-lg:`, `hover:` y `dark:` escriben la regla `@media` o el selector, y utilidades como `backdrop-blur-md` y `bg-clip-text` añaden las declaraciones `-webkit-`. Los corchetes aceptan cualquier valor, como en `w-[1240px]`, y los paréntesis leen una propiedad personalizada, como en `text-(--muted)`. Cada `--color-<nombre>` de los estilos globales se convierte en un color, como en `bg-brand`. Una utilidad desconocida detiene el build con el archivo y la línea. La página **Styles** del sitio de documentación (`#style-docs`) enumera cada clase con su CSS; `node tools/style-docs.mjs` la vuelve a generar a partir del catálogo del paquete.
131
+
132
+ Los iconos son opcionales y viven en su propio paquete. Instala `@aliens-syndicate/icons` y declaralo en `.config` en `icons:` con `from: @aliens-syndicate/icons` y un `style:` predeterminado. Los iconos pertenecen al markup, sin span y sin clase: `icon add-01 size-4 blue-500 red-500` nombra el icono y después, en cualquier orden, uno de los diez estilos, un tamaño, hasta dos colores (el segundo pinta el tono claro de bulk, duotone y twotone) y un estado como `disabled` o `hidden`; `id`, `variant` y `label` son sus únicos atributos. El build dibuja cada icono inline, y un proyecto sin el paquete se genera igual. La página **Icons** (`#icon-docs`) lista los 6070 iconos por categoría y copia la etiqueta de cualquiera; `node tools/icon-docs.mjs` la regenera a partir del paquete.
133
+
134
+ Los Elements listos también son opcionales y viven en `@aliens-syndicate/elements`; un proyecto nuevo empieza sin ellos. Instala el paquete y decláralo en `.config` bajo `elements:` con `from: @aliens-syndicate/elements`, y cualquier markup puede escribir `ui-button`, `ui-icon-button`, `ui-badge`, `ui-alert`, `ui-card`, `ui-avatar`, `ui-spinner`, `ui-progress`, `ui-stat`, `ui-accordion`, `ui-empty-state`, `ui-divider`, `ui-text-field`, `ui-checkbox` y `ui-switch` con sus propiedades, como en `ui-button label="Guardar" variant="ui-button_primary" action="save"`. Son archivos Space como los Elements del proyecto: el build los valida, `ai/.map` los lista y solo los Elements que la página renderiza llegan a `dist/`. Sus estilos son CSS puro que lee los tokens del starter, y un `.style` del proyecto con los mismos nombres de variant los sobrescribe. La página **Elements** (`#element-docs`) muestra cada uno en vivo, con sus propiedades y su código.
135
+
117
136
  #### Logic
118
137
 
119
- `bind:` lista cada `id` del Element con lo que un signal define en la etiqueta. Las expresiones usan el mismo JavaScript que `body:`. Una entrada `_modificador` activa y desactiva el modificador en la etiqueta: `_menu-open` en `home` aplica `home_menu-open`. `page:` indica el signal que controla el tema o el idioma de la página.
138
+ `bind:` lista cada `id` del Element con lo que un signal define en la etiqueta. Las expresiones usan el mismo JavaScript que `body:`. Una entrada `_modificador` activa y desactiva el modificador en la etiqueta: `_menu-open` en `site-header` aplica `site-header_menu-open`. `page:` indica el signal que controla el tema o el idioma de la página.
120
139
 
121
140
  ```text
122
- Logic Home
141
+ Logic SiteHeader
123
142
  signal menuOpen: boolean = false
124
143
 
125
144
  bind:
126
- home:
145
+ site-header:
127
146
  _menu-open: this.menuOpen
128
147
  site-header-menu-toggle:
129
148
  expanded: this.menuOpen
@@ -147,6 +166,30 @@ Un `id` con el formato `<element>-<signal>` no necesita `bind:` para el texto: `
147
166
 
148
167
  Las etiquetas nativas aceptan las mismas propiedades cortas que los Elements: `variant` se convierte en `class`, `action` en `data-action`, `label` en `aria-label` y `text` en el texto de la etiqueta. `button` recibe `type="button"` cuando no declara `type`.
149
168
 
169
+ #### Listas y for
170
+
171
+ `list <nombre>:` en el `.logic` declara una lista fija. Cada elemento tiene un nombre, y ese nombre es su identidad: no hay `track` que declarar. En el markup, `for <item> in <lista>` repite las etiquetas que tiene debajo, y cada campo se lee como `{$item.campo}`.
172
+
173
+ ```text
174
+ Logic SiteHeader
175
+ list links:
176
+ agent:
177
+ href: #agent
178
+ label: @nav.agent
179
+ files:
180
+ href: #files-index
181
+ label: @nav.files
182
+ ```
183
+
184
+ ```text
185
+ Markup SiteHeader
186
+ nav id="site-header-nav"
187
+ for link in links
188
+ nav-item href={$link.href} label={$link.label}
189
+ ```
190
+
191
+ El build escribe el nombre del elemento como `data-key` en la primera etiqueta de cada repetición. `{$item.key}` y `{$item.index}` (desde cero) vienen incluidos, por eso `key` e `index` no pueden ser nombres de campo. La lista viene del `.logic` del Element o de un Element a su alrededor. Los nombres repetidos, los campos inexistentes y las listas desconocidas detienen el build con archivo y línea. Las listas se renderizan con la página; el runtime aún no las actualiza.
192
+
150
193
  ### Elements con solo los archivos necesarios
151
194
 
152
195
  Un Element es el conjunto de archivos con el mismo nombre en la misma carpeta. Ningún archivo es obligatorio, y el build reconoce cada uno por su nombre y extensión.
package/README.md CHANGED
@@ -12,14 +12,28 @@ cd my-project
12
12
  node tools/build.mjs
13
13
  ```
14
14
 
15
- The same generator is published on npm as `@aliens-syndicate/cli` and works without cloning the repository. The `aliens build` command runs the `tools/build.mjs` of the project you are in.
15
+ The same generator is published on npm as `@aliens-syndicate/cli` and works without cloning the repository. Install it once with `npm install -g @aliens-syndicate/cli`; `aliens new` asks which extensions to use and runs `npm install`. Comments that start with `#AGENT` are directives for AI agents only: the build lists them, with file and line, under `directives:` in `ai/.map`.
16
16
 
17
17
  ```sh
18
- npx @aliens-syndicate/cli create my-project
18
+ npm install -g @aliens-syndicate/cli
19
+ aliens new my-project
19
20
  cd my-project
20
- npx @aliens-syndicate/cli build
21
+ aliens run
21
22
  ```
22
23
 
24
+ | Command | What it does |
25
+ | --- | --- |
26
+ | `aliens new <name>` (`n`) | Creates a project and asks which extensions to install. `--yes`, `--no-style`, `--no-icons`, `--no-elements` and `--skip-install` skip the questions. |
27
+ | `aliens run` | Builds, serves on http://localhost:5151 and rebuilds and reloads the browser on every save. `--port <number>` or `serve: port:` in `.config` changes the port. `aliens watch` is an alias. |
28
+ | `aliens build` | Runs the `tools/build.mjs` of the project and generates `dist/` and `ai/.map`. |
29
+ | `aliens generate <kind> <name>` (`g`) | Creates Space files. `aliens g element molecules/card` writes `.markup`, `.logic`, `.style` and `.test`; without the level the CLI asks. Existing files are kept and only the missing ones are added. Kinds: element (`e`), page (`p`), service (`s`), directive (`d`), interface (`i`), model (`m`), validator (`v`), route (`r`), api, animation, enum, error, guard, interceptor, mock, pipe, storage, agent, rule, skill. `--dry-run` writes nothing. |
30
+ | `aliens doctor` | Checks Node.js, npm, the CLI version, `.config`, the packages, the port and the build, with the fix for each problem. |
31
+ | `aliens update` | Updates the `@aliens-syndicate` packages of the project and copies the `tools/` of the installed CLI. `--dry-run` lists the changes. |
32
+ | `aliens cache` | Deletes `dist/` and the caches the tools keep. |
33
+ | `aliens version` | Shows the CLI, Node.js, system and package versions. `aliens --version` prints only the number. |
34
+
35
+ The comment at the top of `.config` lists the same commands, and the **Installation** page of the site (`#installation`) walks through them step by step.
36
+
23
37
  To publish a new version, update `version` in `package.json` and run `npm publish` at the root, with the `aliens-syndicate` account logged in to npm.
24
38
 
25
39
  The generator creates the Home in `project/app/pages/home/`, the four Element levels and the folders for the application file types. The commented examples of the hero catalog come from the engine base in `tools/starter/`, regardless of the application you have open. The `hero-card` Element brings together `.markup`, `.logic`, `.style` and `.test` in `project/app/elements/molecules/hero-card/`. The `agents/`, `rules/` and `skills/` folders live in `ai/`.
@@ -107,23 +121,28 @@ Write the name without `#` or `.`. The build generates `[id="name"]` for an `id`
107
121
  ```text
108
122
  Style Counter
109
123
  counter-button
110
- border: 1px solid var(--line-strong)
124
+ flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
125
+ hover:border-(--accent-stroke) max-md:w-full
111
126
  counter-button_increase
112
- background: var(--primary)
113
- counter-button:hover
114
- border-color: var(--accent-stroke)
127
+ bg-(--primary) text-(--primary-ink)
115
128
  ```
116
129
 
130
+ Inside a selector, a line written as `property: value` is a CSS declaration. By default `.style` reads plain CSS only. Utilities are optional and live in their own package: install `@aliens-syndicate/style` and declare it in `.config` under `style:` with `from: @aliens-syndicate/style`. Without it, a utility line stops the build and says how to add the package. With it, any other line lists utilities with the names popularized by existing CSS frameworks: `flex`, `gap-4`, `rounded-lg`, `text-sm`. Variants such as `md:`, `max-lg:`, `hover:` and `dark:` write the `@media` rule or the selector, and utilities such as `backdrop-blur-md` and `bg-clip-text` add the `-webkit-` declarations. Brackets take any value, as in `w-[1240px]`, and parentheses read a custom property, as in `text-(--muted)`. Each `--color-<name>` in the global styles becomes a color, as in `bg-brand`. An unknown utility stops the build with the file and the line. The **Styles** page of the documentation site (`#style-docs`) lists every class with its CSS; `node tools/style-docs.mjs` regenerates it from the package's catalog.
131
+
132
+ Icons are optional and live in their own package. Install `@aliens-syndicate/icons` and declare it in `.config` under `icons:` with `from: @aliens-syndicate/icons` and a default `style:`. Icons belong to the markup, with no span and no class: `icon add-01 size-4 blue-500 red-500` names the icon and then, in any order, one of the ten styles, a size, up to two colors (the second paints the light tone of bulk, duotone and twotone) and a state such as `disabled` or `hidden`; `id`, `variant` and `label` are its only attributes. The build draws each icon inline, and a project without the package builds the same way. The **Icons** page (`#icon-docs`) lists all 6,070 icons by category and copies the tag of any of them; `node tools/icon-docs.mjs` regenerates it from the package.
133
+
134
+ Ready-made Elements are optional too and live in `@aliens-syndicate/elements`; a new project starts without them. Install the package and declare it in `.config` under `elements:` with `from: @aliens-syndicate/elements`, and any markup can write `ui-button`, `ui-icon-button`, `ui-badge`, `ui-alert`, `ui-card`, `ui-avatar`, `ui-spinner`, `ui-progress`, `ui-stat`, `ui-accordion`, `ui-empty-state`, `ui-divider`, `ui-text-field`, `ui-checkbox` and `ui-switch` with their properties, as in `ui-button label="Save" variant="ui-button_primary" action="save"`. They are Space files like the Elements of the project: the build validates them, `ai/.map` lists them, and only the Elements a page renders reach `dist/`. Their styles are plain CSS that read the starter tokens, and a project `.style` with the same variant names overrides them. The **Elements** page (`#element-docs`) shows each one live, with its properties and source.
135
+
117
136
  #### Logic
118
137
 
119
- `bind:` lists each `id` of the Element with what a signal sets on the tag. Expressions use the same JavaScript as `body:`. A `_modifier` entry toggles the modifier on the tag: `_menu-open` on `home` applies `home_menu-open`. `page:` names the signal that controls the page theme or language.
138
+ `bind:` lists each `id` of the Element with what a signal sets on the tag. Expressions use the same JavaScript as `body:`. A `_modifier` entry toggles the modifier on the tag: `_menu-open` on `site-header` applies `site-header_menu-open`. `page:` names the signal that controls the page theme or language.
120
139
 
121
140
  ```text
122
- Logic Home
141
+ Logic SiteHeader
123
142
  signal menuOpen: boolean = false
124
143
 
125
144
  bind:
126
- home:
145
+ site-header:
127
146
  _menu-open: this.menuOpen
128
147
  site-header-menu-toggle:
129
148
  expanded: this.menuOpen
@@ -147,6 +166,30 @@ An `id` in the `<element>-<signal>` format needs no `bind:` for text: `counter-v
147
166
 
148
167
  Native tags accept the same short properties as Elements: `variant` becomes `class`, `action` becomes `data-action`, `label` becomes `aria-label` and `text` becomes the tag text. `button` gets `type="button"` when it declares no `type`.
149
168
 
169
+ #### Lists and for
170
+
171
+ `list <name>:` in a `.logic` declares a fixed list. Each item has a name, and that name is its identity: there is no `track` to declare. In markup, `for <item> in <list>` repeats the tags below it, and each field is read as `{$item.field}`.
172
+
173
+ ```text
174
+ Logic SiteHeader
175
+ list links:
176
+ agent:
177
+ href: #agent
178
+ label: @nav.agent
179
+ files:
180
+ href: #files-index
181
+ label: @nav.files
182
+ ```
183
+
184
+ ```text
185
+ Markup SiteHeader
186
+ nav id="site-header-nav"
187
+ for link in links
188
+ nav-item href={$link.href} label={$link.label}
189
+ ```
190
+
191
+ The build writes the item name as `data-key` on the first tag of each repetition. `{$item.key}` and `{$item.index}` (starting at zero) are built in, so `key` and `index` can't be field names. The list comes from the `.logic` of the Element or of an Element around it. Duplicate names, missing fields, and unknown lists stop the build with file and line. Lists render with the page; the runtime doesn't update them yet.
192
+
150
193
  ### Elements with only the files they need
151
194
 
152
195
  An Element is the set of files with the same name in the same folder. No file is required, and the build recognizes each one by its name and extension.
package/README.pt-BR.md CHANGED
@@ -12,14 +12,28 @@ cd meu-projeto
12
12
  node tools/build.mjs
13
13
  ```
14
14
 
15
- O mesmo gerador está publicado no npm como `@aliens-syndicate/cli` e funciona sem clonar o repositório. O comando `aliens build` executa o `tools/build.mjs` do projeto aberto.
15
+ O mesmo gerador está publicado no npm como `@aliens-syndicate/cli` e funciona sem clonar o repositório. Instale uma vez com `npm install -g @aliens-syndicate/cli`; o `aliens new` pergunta quais extensões usar e roda o `npm install`. Comentários que começam com `#AGENT` são diretivas só para agentes de IA: o build os lista, com arquivo e linha, em `directives:` no `ai/.map`.
16
16
 
17
17
  ```sh
18
- npx @aliens-syndicate/cli create meu-projeto
18
+ npm install -g @aliens-syndicate/cli
19
+ aliens new meu-projeto
19
20
  cd meu-projeto
20
- npx @aliens-syndicate/cli build
21
+ aliens run
21
22
  ```
22
23
 
24
+ | Comando | O que faz |
25
+ | --- | --- |
26
+ | `aliens new <nome>` (`n`) | Cria um projeto e pergunta quais extensões instalar. `--yes`, `--no-style`, `--no-icons`, `--no-elements` e `--skip-install` pulam as perguntas. |
27
+ | `aliens run` | Faz o build, serve em http://localhost:5151 e refaz o build e recarrega o navegador a cada arquivo salvo. `--port <número>` ou `serve: port:` no `.config` troca a porta. `aliens watch` é um atalho. |
28
+ | `aliens build` | Executa o `tools/build.mjs` do projeto e gera `dist/` e `ai/.map`. |
29
+ | `aliens generate <tipo> <nome>` (`g`) | Cria arquivos Space. `aliens g element molecules/card` escreve `.markup`, `.logic`, `.style` e `.test`; sem o nível, a CLI pergunta. Arquivos que já existem são mantidos e só os que faltam são criados. Tipos: element (`e`), page (`p`), service (`s`), directive (`d`), interface (`i`), model (`m`), validator (`v`), route (`r`), api, animation, enum, error, guard, interceptor, mock, pipe, storage, agent, rule, skill. `--dry-run` não grava nada. |
30
+ | `aliens doctor` | Verifica Node.js, npm, a versão da CLI, o `.config`, os pacotes, a porta e o build, com a correção de cada problema. |
31
+ | `aliens update` | Atualiza os pacotes `@aliens-syndicate` do projeto e copia o `tools/` da CLI instalada. `--dry-run` lista as mudanças. |
32
+ | `aliens cache` | Apaga o `dist/` e os caches das ferramentas. |
33
+ | `aliens version` | Mostra as versões da CLI, do Node.js, do sistema e dos pacotes. `aliens --version` mostra só o número. |
34
+
35
+ O comentário no topo do `.config` lista os mesmos comandos, e a página **Instalação** do site (`#installation`) explica cada um passo a passo.
36
+
23
37
  Para publicar uma nova versão, atualize `version` em `package.json` e execute `npm publish` na raiz, com a conta `aliens-syndicate` logada no npm.
24
38
 
25
39
  O gerador cria a Home em `project/app/pages/home/`, os quatro níveis de Elements e as pastas dos tipos de arquivo da aplicação. Os exemplos comentados do catálogo de heróis vêm da base do motor em `tools/starter/`, independente da aplicação que estiver aberta. O Element `hero-card` reúne `.markup`, `.logic`, `.style` e `.test` em `project/app/elements/molecules/hero-card/`. As pastas `agents/`, `rules/` e `skills/` ficam em `ai/`.
@@ -107,23 +121,28 @@ Escreva o nome sem `#` ou `.`. O build gera `[id="nome"]` para um `id` e `.nome`
107
121
  ```text
108
122
  Style Counter
109
123
  counter-button
110
- border: 1px solid var(--line-strong)
124
+ flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
125
+ hover:border-(--accent-stroke) max-md:w-full
111
126
  counter-button_increase
112
- background: var(--primary)
113
- counter-button:hover
114
- border-color: var(--accent-stroke)
127
+ bg-(--primary) text-(--primary-ink)
115
128
  ```
116
129
 
130
+ Dentro de um seletor, uma linha escrita como `propriedade: valor` é uma declaração CSS. Por padrão, `.style` aceita apenas CSS normal. Os utilitários são opcionais e ficam num pacote próprio: instale `@aliens-syndicate/style` e declare-o no `.config` em `style:` com `from: @aliens-syndicate/style`. Sem ele, uma linha de utilitários interrompe o build e diz como adicionar o pacote. Com ele, qualquer outra linha lista utilitários com os nomes popularizados por frameworks de CSS existentes: `flex`, `gap-4`, `rounded-lg`, `text-sm`. Variantes como `md:`, `max-lg:`, `hover:` e `dark:` escrevem a regra `@media` ou o seletor, e utilitários como `backdrop-blur-md` e `bg-clip-text` acrescentam as declarações `-webkit-`. Colchetes aceitam qualquer valor, como em `w-[1240px]`, e parênteses leem uma propriedade customizada, como em `text-(--muted)`. Cada `--color-<nome>` dos estilos globais vira uma cor, como em `bg-brand`. Um utilitário desconhecido interrompe o build com o arquivo e a linha. A página **Styles** do site de documentação (`#style-docs`) lista cada classe com o seu CSS; `node tools/style-docs.mjs` a gera de novo a partir do catálogo do pacote.
131
+
132
+ Os ícones são opcionais e ficam em um pacote próprio. Instale `@aliens-syndicate/icons` e declare no `.config` em `icons:` com `from: @aliens-syndicate/icons` e um `style:` padrão. Os ícones pertencem ao markup, sem span e sem classe: `icon add-01 size-4 blue-500 red-500` dá o nome do ícone e depois, em qualquer ordem, um dos dez estilos, um tamanho, até duas cores (a segunda pinta o tom claro do bulk, duotone e twotone) e um estado como `disabled` ou `hidden`; `id`, `variant` e `label` são seus únicos atributos. O build desenha cada ícone inline, e um projeto sem o pacote é gerado do mesmo jeito. A página **Icons** (`#icon-docs`) lista os 6.070 ícones por categoria e copia a tag de qualquer um; `node tools/icon-docs.mjs` a regenera a partir do pacote.
133
+
134
+ Os Elements prontos também são opcionais e ficam em `@aliens-syndicate/elements`; um projeto novo começa sem eles. Instale o pacote e declare no `.config` em `elements:` com `from: @aliens-syndicate/elements`, e qualquer markup pode escrever `ui-button`, `ui-icon-button`, `ui-badge`, `ui-alert`, `ui-card`, `ui-avatar`, `ui-spinner`, `ui-progress`, `ui-stat`, `ui-accordion`, `ui-empty-state`, `ui-divider`, `ui-text-field`, `ui-checkbox` e `ui-switch` com suas propriedades, como em `ui-button label="Salvar" variant="ui-button_primary" action="save"`. Eles são arquivos Space como os Elements do projeto: o build os valida, o `ai/.map` os lista e só os Elements que a página renderiza chegam ao `dist/`. Os estilos são CSS puro que lê os tokens do starter, e um `.style` do projeto com os mesmos nomes de variant os sobrescreve. A página **Elements** (`#element-docs`) mostra cada um ao vivo, com propriedades e código.
135
+
117
136
  #### Logic
118
137
 
119
- `bind:` lista cada `id` do Element com o que um signal define na tag. As expressões usam o mesmo JavaScript do `body:`. Uma entrada `_modificador` liga e desliga o modificador na tag: `_menu-open` em `home` aplica `home_menu-open`. `page:` indica o signal que controla o tema ou o idioma da página.
138
+ `bind:` lista cada `id` do Element com o que um signal define na tag. As expressões usam o mesmo JavaScript do `body:`. Uma entrada `_modificador` liga e desliga o modificador na tag: `_menu-open` em `site-header` aplica `site-header_menu-open`. `page:` indica o signal que controla o tema ou o idioma da página.
120
139
 
121
140
  ```text
122
- Logic Home
141
+ Logic SiteHeader
123
142
  signal menuOpen: boolean = false
124
143
 
125
144
  bind:
126
- home:
145
+ site-header:
127
146
  _menu-open: this.menuOpen
128
147
  site-header-menu-toggle:
129
148
  expanded: this.menuOpen
@@ -147,6 +166,30 @@ Um `id` no formato `<element>-<signal>` dispensa o `bind:` para texto: `counter-
147
166
 
148
167
  Tags nativas aceitam as mesmas propriedades curtas dos Elements: `variant` vira `class`, `action` vira `data-action`, `label` vira `aria-label` e `text` vira o texto da tag. `button` recebe `type="button"` quando não declara `type`.
149
168
 
169
+ #### Listas e for
170
+
171
+ `list <nome>:` no `.logic` declara uma lista fixa. Cada item tem um nome, e esse nome é a identidade dele: não existe `track` para declarar. No markup, `for <item> in <lista>` repete as tags abaixo dele, e cada campo é lido como `{$item.campo}`.
172
+
173
+ ```text
174
+ Logic SiteHeader
175
+ list links:
176
+ agent:
177
+ href: #agent
178
+ label: @nav.agent
179
+ files:
180
+ href: #files-index
181
+ label: @nav.files
182
+ ```
183
+
184
+ ```text
185
+ Markup SiteHeader
186
+ nav id="site-header-nav"
187
+ for link in links
188
+ nav-item href={$link.href} label={$link.label}
189
+ ```
190
+
191
+ O build grava o nome do item como `data-key` na primeira tag de cada repetição. `{$item.key}` e `{$item.index}` (a partir de zero) já vêm prontos, por isso `key` e `index` não podem ser nomes de campo. A lista vem do `.logic` do Element ou de um Element ao redor. Nomes repetidos, campos inexistentes e listas desconhecidas param o build com arquivo e linha. As listas são renderizadas com a página; o runtime ainda não as atualiza.
192
+
150
193
  ### Elements com os arquivos necessários
151
194
 
152
195
  Um Element é o conjunto de arquivos com o mesmo nome na mesma pasta. Nenhum arquivo é obrigatório, e o build reconhece cada um pelo nome e pela extensão.
package/README.zh-CN.md CHANGED
@@ -12,14 +12,28 @@ cd my-project
12
12
  node tools/build.mjs
13
13
  ```
14
14
 
15
- 同一个生成器已作为 `@aliens-syndicate/cli` 发布到 npm,无需克隆仓库即可使用。`aliens build` 命令会运行当前项目中的 `tools/build.mjs`。
15
+ 同一个生成器已作为 `@aliens-syndicate/cli` 发布到 npm,无需克隆仓库即可使用。用 `npm install -g @aliens-syndicate/cli` 安装一次;`aliens new` 会询问要使用哪些扩展并运行 `npm install`。以 `#AGENT` 开头的注释是只面向 AI 智能体的指令:构建会把它们连同文件和行号列在 `ai/.map` 的 `directives:` 中。
16
16
 
17
17
  ```sh
18
- npx @aliens-syndicate/cli create my-project
18
+ npm install -g @aliens-syndicate/cli
19
+ aliens new my-project
19
20
  cd my-project
20
- npx @aliens-syndicate/cli build
21
+ aliens run
21
22
  ```
22
23
 
24
+ | 命令 | 作用 |
25
+ | --- | --- |
26
+ | `aliens new <名称>`(`n`) | 创建项目,并询问要安装哪些扩展。`--yes`、`--no-style`、`--no-icons`、`--no-elements` 和 `--skip-install` 可跳过提问。 |
27
+ | `aliens run` | 构建并在 http://localhost:5151 上提供服务,每次保存都会重新构建并刷新浏览器。`--port <端口>` 或 `.config` 中的 `serve: port:` 可更改端口。`aliens watch` 是别名。 |
28
+ | `aliens build` | 运行项目的 `tools/build.mjs`,生成 `dist/` 和 `ai/.map`。 |
29
+ | `aliens generate <类型> <名称>`(`g`) | 创建 Space 文件。`aliens g element molecules/card` 会写入 `.markup`、`.logic`、`.style` 和 `.test`;不写层级时 CLI 会询问。已存在的文件会保留,只补上缺少的。类型:element(`e`)、page(`p`)、service(`s`)、directive(`d`)、interface(`i`)、model(`m`)、validator(`v`)、route(`r`)、api、animation、enum、error、guard、interceptor、mock、pipe、storage、agent、rule、skill。`--dry-run` 不写入任何文件。 |
30
+ | `aliens doctor` | 检查 Node.js、npm、CLI 版本、`.config`、依赖包、端口和构建,并给出每个问题的修复方法。 |
31
+ | `aliens update` | 更新项目的 `@aliens-syndicate` 包,并复制已安装 CLI 的 `tools/`。`--dry-run` 只列出更改。 |
32
+ | `aliens cache` | 删除 `dist/` 和工具保留的缓存。 |
33
+ | `aliens version` | 显示 CLI、Node.js、系统和依赖包的版本。`aliens --version` 只输出版本号。 |
34
+
35
+ `.config` 顶部的注释列出了同样的命令,网站的 **安装** 页面(`#installation`)会一步步讲解。
36
+
23
37
  要发布新版本,请更新 `package.json` 中的 `version`,并在已登录 `aliens-syndicate` 账号的情况下于根目录运行 `npm publish`。
24
38
 
25
39
  生成器会在 `project/app/pages/home/` 中创建首页,并创建四个 Element 层级以及应用各文件类型的文件夹。英雄目录的注释示例来自引擎基础目录 `tools/starter/`,与当前打开的应用无关。`hero-card` Element 在 `project/app/elements/molecules/hero-card/` 中包含 `.markup`、`.logic`、`.style` 和 `.test`。`agents/`、`rules/` 和 `skills/` 文件夹位于 `ai/`。
@@ -107,23 +121,28 @@ Markup Counter
107
121
  ```text
108
122
  Style Counter
109
123
  counter-button
110
- border: 1px solid var(--line-strong)
124
+ flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
125
+ hover:border-(--accent-stroke) max-md:w-full
111
126
  counter-button_increase
112
- background: var(--primary)
113
- counter-button:hover
114
- border-color: var(--accent-stroke)
127
+ bg-(--primary) text-(--primary-ink)
115
128
  ```
116
129
 
130
+ 在选择器内部,写成 `属性: 值` 的行是 CSS 声明。默认情况下 `.style` 只接受普通 CSS。工具类是可选的,位于独立的包中:安装 `@aliens-syndicate/style`,并在 `.config` 的 `style:` 下声明 `from: @aliens-syndicate/style`。没有该包时,工具类行会让构建停止并提示如何添加它。有了该包,其他行列出现有 CSS 框架普及的工具类名称:`flex`、`gap-4`、`rounded-lg`、`text-sm`。`md:`、`max-lg:`、`hover:` 和 `dark:` 等变体会写出 `@media` 规则或选择器,`backdrop-blur-md` 和 `bg-clip-text` 等工具类会补上 `-webkit-` 声明。方括号接受任意值,例如 `w-[1240px]`;圆括号读取自定义属性,例如 `text-(--muted)`。全局样式中的每个 `--color-<名称>` 都会成为颜色,例如 `bg-brand`。未知的工具类会让构建停止,并给出文件和行号。文档站点的 **Styles** 页面(`#style-docs`)列出了每个类及其 CSS;`node tools/style-docs.mjs` 会根据该包的目录重新生成该页面。
131
+
132
+ 图标是可选的,位于独立的包中。安装 `@aliens-syndicate/icons`,在 `.config` 的 `icons:` 下写 `from: @aliens-syndicate/icons` 和默认的 `style:`。图标属于 markup,不需要 span,也不需要 class:`icon add-01 size-4 blue-500 red-500` 先写图标名称,再按任意顺序写十种样式之一、尺寸、最多两种颜色(第二种用于 bulk、duotone 和 twotone 的浅色部分),以及 `disabled` 或 `hidden` 等状态;`id`、`variant` 和 `label` 是它仅有的属性。构建会把每个图标内联绘制,没有该包的项目照常构建。**Icons**页面(`#icon-docs`)按分类列出全部 6,070 个图标,并可复制任意图标的标签;`node tools/icon-docs.mjs` 会根据该包重新生成它。
133
+
134
+ 现成的 Element 同样是可选的,位于 `@aliens-syndicate/elements` 包中;新项目默认不包含它们。安装该包,并在 `.config` 的 `elements:` 下写入 `from: @aliens-syndicate/elements`,任何 markup 就可以使用 `ui-button`、`ui-icon-button`、`ui-badge`、`ui-alert`、`ui-card`、`ui-avatar`、`ui-spinner`、`ui-progress`、`ui-stat`、`ui-accordion`、`ui-empty-state`、`ui-divider`、`ui-text-field`、`ui-checkbox` 和 `ui-switch` 及其属性,例如 `ui-button label="保存" variant="ui-button_primary" action="save"`。它们和项目中的 Element 一样是 Space 文件:构建会校验它们,`ai/.map` 会列出它们,只有页面实际渲染的 Element 才会进入 `dist/`。它们的样式是读取 starter 令牌的纯 CSS,项目中使用相同 variant 名称的 `.style` 可以覆盖它们。**Elements** 页面(`#element-docs`)实时展示每个 Element 及其属性和源码。
135
+
117
136
  #### Logic
118
137
 
119
- `bind:` 列出 Element 的每个 `id`,以及 signal 在该标签上设置的内容。表达式使用与 `body:` 相同的 JavaScript。`_modifier` 条目会在标签上切换修饰符:`home` 上的 `_menu-open` 会应用 `home_menu-open`。`page:` 指定控制页面主题或语言的 signal。
138
+ `bind:` 列出 Element 的每个 `id`,以及 signal 在该标签上设置的内容。表达式使用与 `body:` 相同的 JavaScript。`_modifier` 条目会在标签上切换修饰符:`site-header` 上的 `_menu-open` 会应用 `site-header_menu-open`。`page:` 指定控制页面主题或语言的 signal。
120
139
 
121
140
  ```text
122
- Logic Home
141
+ Logic SiteHeader
123
142
  signal menuOpen: boolean = false
124
143
 
125
144
  bind:
126
- home:
145
+ site-header:
127
146
  _menu-open: this.menuOpen
128
147
  site-header-menu-toggle:
129
148
  expanded: this.menuOpen
@@ -147,6 +166,30 @@ Logic Home
147
166
 
148
167
  原生标签接受与 Element 相同的简写属性:`variant` 变为 `class`,`action` 变为 `data-action`,`label` 变为 `aria-label`,`text` 变为标签文本。未声明 `type` 的 `button` 会获得 `type="button"`。
149
168
 
169
+ #### 列表和 for
170
+
171
+ `.logic` 中的 `list <名称>:` 声明一个固定列表。每一项都有名称,这个名称就是它的标识:无需声明 `track`。在 markup 中,`for <项> in <列表>` 会重复其下方的标签,每个字段以 `{$项.字段}` 读取。
172
+
173
+ ```text
174
+ Logic SiteHeader
175
+ list links:
176
+ agent:
177
+ href: #agent
178
+ label: @nav.agent
179
+ files:
180
+ href: #files-index
181
+ label: @nav.files
182
+ ```
183
+
184
+ ```text
185
+ Markup SiteHeader
186
+ nav id="site-header-nav"
187
+ for link in links
188
+ nav-item href={$link.href} label={$link.label}
189
+ ```
190
+
191
+ 构建会把项名称作为 `data-key` 写入每次重复的第一个标签。`{$item.key}` 和 `{$item.index}`(从零开始)是内置的,因此 `key` 和 `index` 不能作为字段名。列表来自该 Element 或其外层 Element 的 `.logic`。重复的名称、不存在的字段和未知的列表会让构建停止并指出文件和行号。列表随页面渲染,运行时暂不更新它们。
192
+
150
193
  ### 只包含所需文件的 Element
151
194
 
152
195
  Element 是同一文件夹中同名文件的集合。没有任何文件是必需的,构建通过名称和扩展名识别每个文件。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aliens-syndicate/cli",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "CLI for Aliens, the AI-era front-end framework written in Space.",
5
5
  "license": "MIT",
6
6
  "author": "Aliens Syndicate",
@@ -29,5 +29,10 @@
29
29
  "homepage": "https://github.com/AliensSyndicate/aliens-syndicate-framework#readme",
30
30
  "publishConfig": {
31
31
  "access": "public"
32
+ },
33
+ "devDependencies": {
34
+ "@aliens-syndicate/elements": "file:../aliens-syndicate-elements",
35
+ "@aliens-syndicate/icons": "^0.1.0",
36
+ "@aliens-syndicate/style": "^0.1.0"
32
37
  }
33
38
  }