uniweb 1.24.4 → 1.24.6
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.
- package/package.json +5 -5
- package/partials/agents.md +1 -0
- package/partials/start.md +106 -19
- package/src/commands/start.js +38 -7
- package/src/framework-index.json +2 -2
- package/src/index.js +21 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uniweb",
|
|
3
|
-
"version": "1.24.
|
|
3
|
+
"version": "1.24.6",
|
|
4
4
|
"description": "Create structured Vite + React sites with content/code separation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -41,15 +41,15 @@
|
|
|
41
41
|
"js-yaml": "^4.3.2",
|
|
42
42
|
"prompts": "^2.4.2",
|
|
43
43
|
"tar": "^7.5.21",
|
|
44
|
-
"@uniweb/content-writer": "~1.3.1",
|
|
45
44
|
"@uniweb/core": "~1.5.1",
|
|
46
45
|
"@uniweb/semantic-parser": "~1.13.0",
|
|
47
|
-
"@uniweb/schemas": "~1.6.7"
|
|
46
|
+
"@uniweb/schemas": "~1.6.7",
|
|
47
|
+
"@uniweb/content-writer": "~1.3.1"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
50
|
"@uniweb/build": "~1.13.2",
|
|
51
|
-
"@uniweb/
|
|
52
|
-
"@uniweb/
|
|
51
|
+
"@uniweb/semantic-parser": "~1.13.0",
|
|
52
|
+
"@uniweb/content-reader": "~1.5.7"
|
|
53
53
|
},
|
|
54
54
|
"peerDependenciesMeta": {
|
|
55
55
|
"@uniweb/build": {
|
package/partials/agents.md
CHANGED
|
@@ -28,6 +28,7 @@ You're building a *system* of section types, not individual pages. That's what m
|
|
|
28
28
|
|
|
29
29
|
| Your situation | Start at |
|
|
30
30
|
|---|---|
|
|
31
|
+
| Building a whole site for someone, content and code | **Part 3**, *Section format* through *Page organization*, then **Part 4**, *Where things go* through *Section wrapper*, *meta.js*, *Semantic theming*, *theme.yml*, *Fonts*. Read the rest when the site calls for it: *Records, queries and parametric pages* for a blog, *Forms* for a contact form |
|
|
31
32
|
| New or nearly empty project | **Part 1**, then Part 4 |
|
|
32
33
|
| Existing project, content task (pages, copy, colors, nav) | **Part 2**, then Part 3 |
|
|
33
34
|
| Existing project, component task (new section type, restyle) | **Part 2**, then Part 4 |
|
package/partials/start.md
CHANGED
|
@@ -19,47 +19,129 @@ that the pages pick by name. One project holds both. The `uniweb` CLI builds and
|
|
|
19
19
|
and brings it into the Uniweb app, where the person can keep editing it visually.
|
|
20
20
|
{{/if}}
|
|
21
21
|
|
|
22
|
-
##
|
|
22
|
+
## Run everything yourself
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
24
|
+
The person may never have used a terminal, and one who has still expects you to take this
|
|
25
|
+
from start to finish. Run every command yourself, and never ask them to run one. They do
|
|
26
|
+
two things, in their browser: sign in, and pay when the site goes live. When a command
|
|
27
|
+
prints an address to finish something in a browser, open it for them and say what it's
|
|
28
|
+
for.
|
|
27
29
|
|
|
28
30
|
Uniweb needs Node.js 22.12 or later. If `node --version` shows an older one, install a
|
|
29
|
-
current one yourself.
|
|
31
|
+
current one yourself. Install Git too if `git --version` fails: it keeps the history of
|
|
32
|
+
your work, and it's what lets edits made in the app merge with yours. On a Mac, that
|
|
33
|
+
check can open a window offering the developer tools: tell them to accept it.
|
|
34
|
+
|
|
35
|
+
## Work with them
|
|
36
|
+
|
|
37
|
+
- Ask only what you can't decide, in plain words. A first version they can react to tells
|
|
38
|
+
you more than a list of questions.
|
|
39
|
+
- Use what they give you: their words, their files, their current site. Don't invent facts
|
|
40
|
+
about them, and say which parts are placeholders.
|
|
41
|
+
{{#unless project}}
|
|
42
|
+
- Write the site in their language, and set `defaultLanguage` in `site.yml` to its code
|
|
43
|
+
(`defaultLanguage: es`). A site that doesn't say is taken to be in English.
|
|
44
|
+
{{/unless}}
|
|
45
|
+
- Keep anything they may want to change in markdown or in a param its `meta.js` declares,
|
|
46
|
+
not in a component's code. That is what they can edit in the app.
|
|
47
|
+
- Show them the site on their computer before you ask them to sign in.
|
|
48
|
+
- Commit each time something works, with a message that says what changed, so either of
|
|
49
|
+
you can go back to it.
|
|
30
50
|
{{#unless project}}
|
|
51
|
+
{{#if nearby}}
|
|
52
|
+
|
|
53
|
+
## A project is already here
|
|
54
|
+
|
|
55
|
+
{{#if oneNearby}}
|
|
56
|
+
{{nearby}}, in this folder, is a Uniweb project.
|
|
57
|
+
{{else}}
|
|
58
|
+
{{nearby}}, in this folder, are Uniweb projects.
|
|
59
|
+
{{/if}}
|
|
60
|
+
To work on one, go there and run `npx uniweb@latest start` again. Create a new one only
|
|
61
|
+
if they ask for it.
|
|
62
|
+
{{/if}}
|
|
31
63
|
|
|
32
64
|
## Create the project
|
|
33
65
|
|
|
66
|
+
{{#if otherProject}}
|
|
34
67
|
```bash
|
|
35
|
-
npx uniweb@latest create <name> --template
|
|
68
|
+
npx uniweb@latest create <name> --template {{template}}
|
|
36
69
|
cd <name>
|
|
37
70
|
```
|
|
38
71
|
|
|
39
72
|
`<name>` is lowercase letters, digits and hyphens, and becomes the project's folder.
|
|
40
|
-
`create` asks no questions when it runs without a terminal.
|
|
41
|
-
section type and two short pages: a working example of each convention, to replace as
|
|
42
|
-
you build. `--template none` is the same project without them.
|
|
43
|
-
{{#if otherProject}}
|
|
73
|
+
`create` asks no questions when it runs without a terminal.
|
|
44
74
|
|
|
45
75
|
Create it outside `{{otherProject}}`: that folder holds another project, and `create`
|
|
46
76
|
does not make one inside it.
|
|
77
|
+
{{else}}
|
|
78
|
+
In a folder set aside for this site, even one that already holds their logo or photos:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npx uniweb@latest create . --template {{template}}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Anywhere else, give the project a folder of its own:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
npx uniweb@latest create <name> --template {{template}}
|
|
88
|
+
cd <name>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`<name>` is lowercase letters, digits and hyphens. `create .` takes its name from the
|
|
92
|
+
folder, or from `--name <name>`, replaces a `README.md` or `.gitignore` already there, and
|
|
93
|
+
stops if any other file is in its way. `create` asks no questions when it runs without a
|
|
94
|
+
terminal, and starts the project's git repository.
|
|
95
|
+
{{/if}}
|
|
96
|
+
|
|
97
|
+
{{#if starter}}
|
|
98
|
+
`starter` has one generic section type and two short pages: a working example of each
|
|
99
|
+
convention, to replace as you build. `--template none` is the same project without them.
|
|
100
|
+
{{else if none}}
|
|
101
|
+
`none` is a project with no section types or pages: you build them all.
|
|
102
|
+
{{else if paste}}
|
|
103
|
+
`paste` runs a React design as it is: replace `src/sections/App.jsx` with theirs, and the
|
|
104
|
+
site shows it. A picture or a web address you rebuild there instead. That is only the
|
|
105
|
+
start, because they can edit in the app only what has left the code. Take it apart as
|
|
106
|
+
[Converting Existing Designs](https://uniweb.io/docs/development/converting-existing.md)
|
|
107
|
+
says: named section types, their text in markdown, its colors in `theme.yml`.
|
|
108
|
+
{{else}}
|
|
109
|
+
`{{template}}` is a working site: its section types are in `src/`, its sample content in
|
|
110
|
+
`site/`. Keep what fits, replace all the sample content with what they asked for, and
|
|
111
|
+
delete what they won't use. The code is theirs, so change whatever the site needs.
|
|
47
112
|
{{/if}}
|
|
113
|
+
|
|
114
|
+
## If their site is already in the Uniweb app
|
|
115
|
+
|
|
116
|
+
Bring it here instead of creating a project:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
npx uniweb@latest login --browser --personal # see "Sign them in", below
|
|
120
|
+
npx uniweb@latest site list # each site, with its id
|
|
121
|
+
npx uniweb@latest clone <site-uuid> <name>
|
|
122
|
+
cd <name>
|
|
123
|
+
npx uniweb@latest start
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
A clone holds the site's content and uses its foundation by version: you can change its
|
|
127
|
+
pages, text and theme here, but not its section types.
|
|
48
128
|
{{/unless}}
|
|
49
129
|
|
|
50
130
|
## Read the project's guide
|
|
51
131
|
|
|
52
132
|
{{#if agents}}
|
|
53
133
|
AGENTS.md, at the project's root, is the manual for this project and its version of
|
|
54
|
-
Uniweb.
|
|
134
|
+
Uniweb. It's long, so read its Part 0 before writing code, then the parts it names for
|
|
135
|
+
your task.
|
|
55
136
|
{{else}}
|
|
56
137
|
This project has no AGENTS.md, the manual for a Uniweb project. Write one with
|
|
57
|
-
`npx uniweb update --agents-only`, then read its Part 0 before writing code
|
|
58
|
-
|
|
138
|
+
`npx uniweb update --agents-only`, then read its Part 0 before writing code, and the parts
|
|
139
|
+
it names for your task.
|
|
59
140
|
{{/if}}
|
|
60
141
|
|
|
61
142
|
Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
|
|
62
|
-
wrong. AGENTS.md says how to check.
|
|
143
|
+
wrong. AGENTS.md says how to check. Look at every page in a browser, wide and narrow,
|
|
144
|
+
before you call it ready.
|
|
63
145
|
{{#if project}}
|
|
64
146
|
|
|
65
147
|
## Check what changed
|
|
@@ -94,8 +176,9 @@ npx uniweb login --browser --personal
|
|
|
94
176
|
```
|
|
95
177
|
|
|
96
178
|
This opens their browser. If they're signed in to Uniweb there, it finishes on its own;
|
|
97
|
-
otherwise they sign in, or sign up if they're new
|
|
98
|
-
|
|
179
|
+
otherwise they sign in, or sign up if they're new. It waits up to five minutes, so give
|
|
180
|
+
the command that long or run it in the background, and run it again if it times out.
|
|
181
|
+
Never ask for a password or a token.
|
|
99
182
|
|
|
100
183
|
`--personal` puts their sites in their own workspace. If they ask for one of their
|
|
101
184
|
organizations instead, use `--org @<its handle>`.
|
|
@@ -108,14 +191,18 @@ npx uniweb publish --commit -m "<what you built>" # to take it live
|
|
|
108
191
|
```
|
|
109
192
|
|
|
110
193
|
`push` sends the site and its foundation to their workspace, where they'll find it in
|
|
111
|
-
the app. `publish` does the same and then takes the site live, so
|
|
112
|
-
first.
|
|
113
|
-
what is
|
|
194
|
+
the app, at https://uniweb.app. `publish` does the same and then takes the site live, so
|
|
195
|
+
it needs no push first. Take it live only when they ask: that's the step they pay for.
|
|
196
|
+
`--commit` commits the site's content first: in a git repository, both send only what is
|
|
197
|
+
committed.
|
|
114
198
|
|
|
115
199
|
If the site needs paying for, `publish` prints an address instead of going live. Open
|
|
116
200
|
it for the person, tell them it's where they pay, and run `publish` again once they're
|
|
117
201
|
done.
|
|
118
202
|
|
|
203
|
+
When the site is in the app, tell them where to find it, and that it isn't live until they
|
|
204
|
+
ask you to take it live or publish it from the app.
|
|
205
|
+
|
|
119
206
|
Once the site is in the app, it can be edited there at any time. Before you change it
|
|
120
207
|
again, and before each push, run `npx uniweb status`: it says what changed in the app
|
|
121
208
|
since your last push or pull, and what to run.
|
package/src/commands/start.js
CHANGED
|
@@ -17,44 +17,75 @@
|
|
|
17
17
|
*
|
|
18
18
|
* It is answered by the CLI that was invoked, never delegated to a project's own copy
|
|
19
19
|
* (`STANDALONE_COMMANDS`): an older project CLI does not have it.
|
|
20
|
+
*
|
|
21
|
+
* ⭐ `--template <name>` names the template the guide creates the project from, so a prompt
|
|
22
|
+
* for a kind of site can say which one and the first command is still this read-only one.
|
|
23
|
+
* The name goes into the guide as given: `create`, which the guide tells the agent to run,
|
|
24
|
+
* is what says when a template does not exist.
|
|
20
25
|
*/
|
|
21
26
|
|
|
22
|
-
import { existsSync, readFileSync } from 'node:fs'
|
|
27
|
+
import { existsSync, readdirSync, readFileSync } from 'node:fs'
|
|
23
28
|
import { dirname, join } from 'node:path'
|
|
24
29
|
import { fileURLToPath } from 'node:url'
|
|
25
30
|
import Handlebars from 'handlebars'
|
|
31
|
+
import { readFlagValue } from '../utils/args.js'
|
|
26
32
|
import { findUniwebWorkspace, findWorkspaceRoot } from '../utils/workspace.js'
|
|
27
33
|
import { detectWorkspacePm, installCmd } from '../utils/pm.js'
|
|
28
34
|
|
|
29
35
|
const PARTIAL = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'partials', 'start.md')
|
|
30
36
|
|
|
37
|
+
/**
|
|
38
|
+
* The Uniweb projects directly inside `cwd`, by folder name. `create <name>` puts a project
|
|
39
|
+
* one level below the folder an agent was opened in, and a later session opened in the same
|
|
40
|
+
* folder has to be told it is there rather than to create another.
|
|
41
|
+
*
|
|
42
|
+
* @param {string} cwd
|
|
43
|
+
* @returns {string[]}
|
|
44
|
+
*/
|
|
45
|
+
function projectsIn(cwd) {
|
|
46
|
+
return readdirSync(cwd, { withFileTypes: true })
|
|
47
|
+
.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
|
|
48
|
+
.map((entry) => entry.name)
|
|
49
|
+
.filter((name) => findUniwebWorkspace(join(cwd, name)) === join(cwd, name))
|
|
50
|
+
.sort()
|
|
51
|
+
}
|
|
52
|
+
|
|
31
53
|
/**
|
|
32
54
|
* The guide, as Markdown, for a command run in `cwd`.
|
|
33
55
|
*
|
|
34
56
|
* Outside a project, `otherProject` names a workspace of another kind that holds `cwd`:
|
|
35
57
|
* `create` refuses to make a project inside one, so the guide says to create it elsewhere.
|
|
36
58
|
*
|
|
37
|
-
* @param {{ cwd?: string }} [o]
|
|
59
|
+
* @param {{ cwd?: string, template?: string|null }} [o] - `template`: what to create the
|
|
60
|
+
* project from, `starter` when none is named
|
|
38
61
|
* @returns {string}
|
|
39
62
|
*/
|
|
40
|
-
export function startGuide({ cwd = process.cwd() } = {}) {
|
|
63
|
+
export function startGuide({ cwd = process.cwd(), template = null } = {}) {
|
|
41
64
|
const root = findUniwebWorkspace(cwd)
|
|
42
|
-
const
|
|
43
|
-
|
|
65
|
+
const nearby = root ? [] : projectsIn(cwd)
|
|
66
|
+
const name = template || 'starter'
|
|
67
|
+
const guide = Handlebars.compile(readFileSync(PARTIAL, 'utf8'), { noEscape: true })
|
|
68
|
+
return guide({
|
|
44
69
|
project: !!root,
|
|
45
70
|
root,
|
|
46
71
|
// A project `create` makes has one; one already here may not.
|
|
47
72
|
agents: root ? existsSync(join(root, 'AGENTS.md')) : true,
|
|
48
73
|
otherProject: root ? null : findWorkspaceRoot(cwd),
|
|
74
|
+
nearby: nearby.map((folder) => `\`${folder}\``).join(', '),
|
|
75
|
+
oneNearby: nearby.length === 1,
|
|
76
|
+
template: name,
|
|
77
|
+
starter: name === 'starter',
|
|
78
|
+
none: name === 'none',
|
|
79
|
+
paste: name === 'paste',
|
|
49
80
|
install: installCmd(root ? detectWorkspacePm(root) : 'npm')
|
|
50
81
|
})
|
|
51
82
|
}
|
|
52
83
|
|
|
53
84
|
/**
|
|
54
|
-
* @param {string[]} [args] -
|
|
85
|
+
* @param {string[]} [args] - `--template <name>`
|
|
55
86
|
* @returns {Promise<{ exitCode: number }>}
|
|
56
87
|
*/
|
|
57
88
|
export async function start(args = []) {
|
|
58
|
-
console.log(startGuide())
|
|
89
|
+
console.log(startGuide({ template: readFlagValue(args, '--template') }))
|
|
59
90
|
return { exitCode: 0 }
|
|
60
91
|
}
|
package/src/framework-index.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
|
-
"generatedAt": "2026-10-
|
|
3
|
+
"generatedAt": "2026-10-31T02:20:56.213Z",
|
|
4
4
|
"packages": {
|
|
5
5
|
"@uniweb/api": {
|
|
6
6
|
"version": "1.6.7"
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"version": "1.1.2"
|
|
55
55
|
},
|
|
56
56
|
"@uniweb/templates": {
|
|
57
|
-
"version": "1.1.
|
|
57
|
+
"version": "1.1.9"
|
|
58
58
|
},
|
|
59
59
|
"@uniweb/theming": {
|
|
60
60
|
"version": "1.2.1"
|
package/src/index.js
CHANGED
|
@@ -1125,6 +1125,21 @@ async function main() {
|
|
|
1125
1125
|
|
|
1126
1126
|
const prefix = getCliPrefix()
|
|
1127
1127
|
|
|
1128
|
+
// ⛔ A SECOND WORD IS REFUSED, not dropped. It is usually a template that lost its flag:
|
|
1129
|
+
// `npm create uniweb my-site --template docs` keeps `--template` for npm, and an agent that
|
|
1130
|
+
// got the starter instead of the docs template had nothing to tell it so.
|
|
1131
|
+
const words = args
|
|
1132
|
+
.slice(1)
|
|
1133
|
+
.filter((arg, i, all) => !arg.startsWith('-') && !(all[i - 1] ?? '').startsWith('-'))
|
|
1134
|
+
if (words.length > 1) {
|
|
1135
|
+
error(`Unexpected argument: ${words[1]}`)
|
|
1136
|
+
log(`\n${prefix} create takes one name. To start from a template:`)
|
|
1137
|
+
log(` ${colors.cyan}${prefix} create ${words[0]} --template ${words[1]}${colors.reset}`)
|
|
1138
|
+
log(`Through npm, which keeps flags for itself:`)
|
|
1139
|
+
log(` ${colors.cyan}npm create uniweb@latest ${words[0]} -- --template ${words[1]}${colors.reset}`)
|
|
1140
|
+
await exitWhenDrained(1)
|
|
1141
|
+
}
|
|
1142
|
+
|
|
1128
1143
|
// In-place: derive the project name from the cwd basename (slugified),
|
|
1129
1144
|
// or use --name when provided. Skip the interactive name prompt below.
|
|
1130
1145
|
if (inPlace) {
|
|
@@ -1385,7 +1400,10 @@ async function main() {
|
|
|
1385
1400
|
)
|
|
1386
1401
|
}
|
|
1387
1402
|
} catch {
|
|
1388
|
-
//
|
|
1403
|
+
// ⛔ Said, not skipped: the project works without git, but it has no history to go back
|
|
1404
|
+
// to and a pull cannot merge, and an agent reading this output has no other way to know.
|
|
1405
|
+
log(` ${colors.yellow}Git is not installed, so this project has no version history.${colors.reset}`)
|
|
1406
|
+
log(` ${colors.dim}Install it, then run: git init && git add -A && git commit -m "Initial commit"${colors.reset}`)
|
|
1389
1407
|
}
|
|
1390
1408
|
}
|
|
1391
1409
|
}
|
|
@@ -1564,7 +1582,8 @@ ${colors.bright}Examples:${colors.reset}
|
|
|
1564
1582
|
${colors.cyan}${colors.bright}uniweb start${colors.reset} ${colors.dim}— How an AI agent begins a Uniweb site${colors.reset}
|
|
1565
1583
|
|
|
1566
1584
|
${colors.bright}Usage:${colors.reset}
|
|
1567
|
-
npx uniweb@latest start
|
|
1585
|
+
npx uniweb@latest start Print the guide, in Markdown
|
|
1586
|
+
npx uniweb@latest start --template docs The guide for a project from that template
|
|
1568
1587
|
|
|
1569
1588
|
A short guide for an AI agent building a website for someone: create a
|
|
1570
1589
|
project, read its AGENTS.md, run it, sign the person in, and bring the site
|