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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.24.4",
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/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,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
- ## 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
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 starter
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. `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}}
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. Read its Part 0 before writing code: it says which parts your task needs.
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: it says
58
- which parts your task needs.
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, and it waits up to five minutes. Never
98
- ask for a password or a token.
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 it needs no push
112
- first. `--commit` commits the site's content first: in a git repository, both send only
113
- what is committed.
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.
@@ -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 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',
49
79
  install: installCmd(root ? detectWorkspacePm(root) : 'npm')
50
80
  })
51
81
  }
52
82
 
53
83
  /**
54
- * @param {string[]} [args] - none are read
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
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-10-30T21:27:31.147Z",
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.7"
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 Print the guide, in Markdown
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