uniweb 1.24.4 → 1.24.5
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 +95 -18
- package/src/commands/start.js +37 -7
- package/src/framework-index.json +2 -2
- package/src/index.js +17 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uniweb",
|
|
3
|
-
"version": "1.24.
|
|
3
|
+
"version": "1.24.5",
|
|
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",
|
|
45
|
+
"@uniweb/schemas": "~1.6.7",
|
|
46
46
|
"@uniweb/semantic-parser": "~1.13.0",
|
|
47
|
-
"@uniweb/
|
|
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,119 @@ 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
31
|
current one yourself.
|
|
32
|
+
|
|
33
|
+
## Work with them
|
|
34
|
+
|
|
35
|
+
- Ask only what you can't decide, in plain words. A first version they can react to tells
|
|
36
|
+
you more than a list of questions.
|
|
37
|
+
- Use what they give you: their words, their files, their current site. Don't invent facts
|
|
38
|
+
about them, and say which parts are placeholders.
|
|
39
|
+
{{#unless project}}
|
|
40
|
+
- Write the site in their language, and set `defaultLanguage` in `site.yml` to its code
|
|
41
|
+
(`defaultLanguage: es`). A site that doesn't say is taken to be in English.
|
|
42
|
+
{{/unless}}
|
|
43
|
+
- Keep anything they may want to change in markdown or in a param its `meta.js` declares,
|
|
44
|
+
not in a component's code. That is what they can edit in the app.
|
|
45
|
+
- Show them the site on their computer before you ask them to sign in.
|
|
30
46
|
{{#unless project}}
|
|
47
|
+
{{#if nearby}}
|
|
48
|
+
|
|
49
|
+
## A project is already here
|
|
50
|
+
|
|
51
|
+
{{#if oneNearby}}
|
|
52
|
+
{{nearby}}, in this folder, is a Uniweb project.
|
|
53
|
+
{{else}}
|
|
54
|
+
{{nearby}}, in this folder, are Uniweb projects.
|
|
55
|
+
{{/if}}
|
|
56
|
+
To work on one, go there and run `npx uniweb@latest start` again. Create a new one only
|
|
57
|
+
if they ask for it.
|
|
58
|
+
{{/if}}
|
|
31
59
|
|
|
32
60
|
## Create the project
|
|
33
61
|
|
|
62
|
+
{{#if otherProject}}
|
|
34
63
|
```bash
|
|
35
|
-
npx uniweb@latest create <name> --template
|
|
64
|
+
npx uniweb@latest create <name> --template {{template}}
|
|
36
65
|
cd <name>
|
|
37
66
|
```
|
|
38
67
|
|
|
39
68
|
`<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}}
|
|
69
|
+
`create` asks no questions when it runs without a terminal.
|
|
44
70
|
|
|
45
71
|
Create it outside `{{otherProject}}`: that folder holds another project, and `create`
|
|
46
72
|
does not make one inside it.
|
|
73
|
+
{{else}}
|
|
74
|
+
In a folder set aside for this site, even one that already holds their logo or photos:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npx uniweb@latest create . --template {{template}}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Anywhere else, give the project a folder of its own:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
npx uniweb@latest create <name> --template {{template}}
|
|
84
|
+
cd <name>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`<name>` is lowercase letters, digits and hyphens. `create .` takes its name from the
|
|
88
|
+
folder, or from `--name <name>`, replaces a `README.md` or `.gitignore` already there, and
|
|
89
|
+
stops if any other file is in its way. `create` asks no questions when it runs without a
|
|
90
|
+
terminal.
|
|
91
|
+
{{/if}}
|
|
92
|
+
|
|
93
|
+
{{#if starter}}
|
|
94
|
+
`starter` has one generic section type and two short pages: a working example of each
|
|
95
|
+
convention, to replace as you build. `--template none` is the same project without them.
|
|
96
|
+
{{else if none}}
|
|
97
|
+
`none` is a project with no section types or pages: you build them all.
|
|
98
|
+
{{else}}
|
|
99
|
+
`{{template}}` is a working site: its section types are in `src/`, its sample content in
|
|
100
|
+
`site/`. Keep what fits, replace all the sample content with what they asked for, and
|
|
101
|
+
delete what they won't use. The code is theirs, so change whatever the site needs.
|
|
47
102
|
{{/if}}
|
|
103
|
+
|
|
104
|
+
## If their site is already in the Uniweb app
|
|
105
|
+
|
|
106
|
+
Bring it here instead of creating a project:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
npx uniweb@latest login --browser --personal # see "Sign them in", below
|
|
110
|
+
npx uniweb@latest site list # each site, with its id
|
|
111
|
+
npx uniweb@latest clone <site-uuid> <name>
|
|
112
|
+
cd <name>
|
|
113
|
+
npx uniweb@latest start
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
A clone holds the site's content and uses its foundation by version: you can change its
|
|
117
|
+
pages, text and theme here, but not its section types.
|
|
48
118
|
{{/unless}}
|
|
49
119
|
|
|
50
120
|
## Read the project's guide
|
|
51
121
|
|
|
52
122
|
{{#if agents}}
|
|
53
123
|
AGENTS.md, at the project's root, is the manual for this project and its version of
|
|
54
|
-
Uniweb.
|
|
124
|
+
Uniweb. It's long, so read its Part 0 before writing code, then the parts it names for
|
|
125
|
+
your task.
|
|
55
126
|
{{else}}
|
|
56
127
|
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
|
-
|
|
128
|
+
`npx uniweb update --agents-only`, then read its Part 0 before writing code, and the parts
|
|
129
|
+
it names for your task.
|
|
59
130
|
{{/if}}
|
|
60
131
|
|
|
61
132
|
Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
|
|
62
|
-
wrong. AGENTS.md says how to check.
|
|
133
|
+
wrong. AGENTS.md says how to check. Look at every page in a browser, wide and narrow,
|
|
134
|
+
before you call it ready.
|
|
63
135
|
{{#if project}}
|
|
64
136
|
|
|
65
137
|
## Check what changed
|
|
@@ -94,8 +166,9 @@ npx uniweb login --browser --personal
|
|
|
94
166
|
```
|
|
95
167
|
|
|
96
168
|
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
|
-
|
|
169
|
+
otherwise they sign in, or sign up if they're new. It waits up to five minutes, so give
|
|
170
|
+
the command that long or run it in the background, and run it again if it times out.
|
|
171
|
+
Never ask for a password or a token.
|
|
99
172
|
|
|
100
173
|
`--personal` puts their sites in their own workspace. If they ask for one of their
|
|
101
174
|
organizations instead, use `--org @<its handle>`.
|
|
@@ -108,14 +181,18 @@ npx uniweb publish --commit -m "<what you built>" # to take it live
|
|
|
108
181
|
```
|
|
109
182
|
|
|
110
183
|
`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
|
|
184
|
+
the app, at https://uniweb.app. `publish` does the same and then takes the site live, so
|
|
185
|
+
it needs no push first. Take it live only when they ask: that's the step they pay for.
|
|
186
|
+
`--commit` commits the site's content first: in a git repository, both send only what is
|
|
187
|
+
committed.
|
|
114
188
|
|
|
115
189
|
If the site needs paying for, `publish` prints an address instead of going live. Open
|
|
116
190
|
it for the person, tell them it's where they pay, and run `publish` again once they're
|
|
117
191
|
done.
|
|
118
192
|
|
|
193
|
+
When the site is in the app, tell them where to find it, and that it isn't live until they
|
|
194
|
+
ask you to take it live or publish it from the app.
|
|
195
|
+
|
|
119
196
|
Once the site is in the app, it can be edited there at any time. Before you change it
|
|
120
197
|
again, and before each push, run `npx uniweb status`: it says what changed in the app
|
|
121
198
|
since your last push or pull, and what to run.
|
package/src/commands/start.js
CHANGED
|
@@ -17,44 +17,74 @@
|
|
|
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',
|
|
49
79
|
install: installCmd(root ? detectWorkspacePm(root) : 'npm')
|
|
50
80
|
})
|
|
51
81
|
}
|
|
52
82
|
|
|
53
83
|
/**
|
|
54
|
-
* @param {string[]} [args] -
|
|
84
|
+
* @param {string[]} [args] - `--template <name>`
|
|
55
85
|
* @returns {Promise<{ exitCode: number }>}
|
|
56
86
|
*/
|
|
57
87
|
export async function start(args = []) {
|
|
58
|
-
console.log(startGuide())
|
|
88
|
+
console.log(startGuide({ template: readFlagValue(args, '--template') }))
|
|
59
89
|
return { exitCode: 0 }
|
|
60
90
|
}
|
package/src/framework-index.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
|
-
"generatedAt": "2026-10-
|
|
3
|
+
"generatedAt": "2026-10-31T01:21:41.232Z",
|
|
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.8"
|
|
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) {
|
|
@@ -1564,7 +1579,8 @@ ${colors.bright}Examples:${colors.reset}
|
|
|
1564
1579
|
${colors.cyan}${colors.bright}uniweb start${colors.reset} ${colors.dim}— How an AI agent begins a Uniweb site${colors.reset}
|
|
1565
1580
|
|
|
1566
1581
|
${colors.bright}Usage:${colors.reset}
|
|
1567
|
-
npx uniweb@latest start
|
|
1582
|
+
npx uniweb@latest start Print the guide, in Markdown
|
|
1583
|
+
npx uniweb@latest start --template docs The guide for a project from that template
|
|
1568
1584
|
|
|
1569
1585
|
A short guide for an AI agent building a website for someone: create a
|
|
1570
1586
|
project, read its AGENTS.md, run it, sign the person in, and bring the site
|