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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.24.4",
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/content-reader": "~1.5.7",
52
- "@uniweb/semantic-parser": "~1.13.0"
51
+ "@uniweb/semantic-parser": "~1.13.0",
52
+ "@uniweb/content-reader": "~1.5.7"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -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
- ## The person doesn't use a terminal
22
+ ## Run everything yourself
23
23
 
24
- Run every command yourself, and never ask them to run one. They do two things, in their
25
- browser: sign in, and pay when the site goes live. When a command prints an address to
26
- finish something in a browser, open it for them and say what it's for.
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 starter
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. `starter` has one generic
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. Read its Part 0 before writing code: it says which parts your task needs.
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: it says
58
- which parts your task needs.
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, and it waits up to five minutes. Never
98
- ask for a password or a token.
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 it needs no push
112
- first. `--commit` commits the site's content first: in a git repository, both send only
113
- what is committed.
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.
@@ -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 template = Handlebars.compile(readFileSync(PARTIAL, 'utf8'), { noEscape: true })
43
- return template({
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] - none are read
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
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-10-30T21:27:31.147Z",
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.7"
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
- // git not available — skip silently
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 Print the guide, in Markdown
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