uniweb 1.25.3 → 1.25.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/README.md +1 -0
- package/package.json +6 -6
- package/partials/agents.md +247 -3138
- package/partials/guides/backend.md +155 -0
- package/partials/guides/content.md +312 -0
- package/partials/guides/data.md +216 -0
- package/partials/guides/foundation.md +321 -0
- package/partials/guides/i18n.md +71 -0
- package/partials/guides/index.json +52 -0
- package/partials/guides/migrate.md +27 -0
- package/partials/guides/services.md +174 -0
- package/partials/guides/ship.md +116 -0
- package/partials/guides/start.md +73 -0
- package/partials/guides/theme.md +123 -0
- package/partials/start.md +12 -11
- package/src/commands/add.js +2 -0
- package/src/commands/build.js +13 -6
- package/src/commands/guide.js +89 -0
- package/src/commands/publish.js +11 -5
- package/src/commands/status.js +30 -5
- package/src/framework-index.json +6 -6
- package/src/index.js +31 -1
- package/src/utils/agents-stamp.js +24 -10
- package/src/utils/flag-guard.js +3 -1
- package/src/utils/scaffold.js +3 -2
- package/templates/workspace/AGENTS.md.hbs +1 -2
- package/templates/workspace/README.md.hbs +2 -1
package/partials/start.md
CHANGED
|
@@ -3,20 +3,21 @@
|
|
|
3
3
|
|
|
4
4
|
You're in the Uniweb project at `{{root}}`.
|
|
5
5
|
|
|
6
|
-
Its pages are
|
|
7
|
-
React components that
|
|
8
|
-
project, and brings it into the Uniweb app, where the person you're working with
|
|
9
|
-
editing it visually.
|
|
6
|
+
Its pages are made of sections: structured content written in markdown, and drawn by its
|
|
7
|
+
foundation, React components that each section picks by name. The `uniweb` CLI builds and
|
|
8
|
+
runs the project, and brings it into the Uniweb app, where the person you're working with
|
|
9
|
+
can keep editing it visually.
|
|
10
10
|
|
|
11
11
|
`uniweb start` only prints this guide; `npx uniweb dev` runs the site. To start a new
|
|
12
12
|
project instead, run `npx uniweb@latest start` in a folder outside this one.
|
|
13
13
|
{{else}}
|
|
14
14
|
# Build a website with Uniweb
|
|
15
15
|
|
|
16
|
-
You're building a website for the person you're working with. In Uniweb,
|
|
17
|
-
|
|
18
|
-
that
|
|
19
|
-
and brings it into the Uniweb app, where the person can keep editing it
|
|
16
|
+
You're building a website for the person you're working with. In Uniweb, a page is made of
|
|
17
|
+
sections: structured content written in markdown, and drawn by a foundation, React
|
|
18
|
+
components that each section picks by name. One project holds both. The `uniweb` CLI builds
|
|
19
|
+
and runs it, and brings it into the Uniweb app, where the person can keep editing it
|
|
20
|
+
visually.
|
|
20
21
|
{{/if}}
|
|
21
22
|
|
|
22
23
|
## Run everything yourself
|
|
@@ -131,12 +132,12 @@ pages, text and theme here, but not its section types.
|
|
|
131
132
|
|
|
132
133
|
{{#if agents}}
|
|
133
134
|
AGENTS.md, at the project's root, is the manual for this project and its version of
|
|
134
|
-
Uniweb.
|
|
135
|
+
Uniweb. Read it before writing code, and follow its procedure, which runs the guide for
|
|
135
136
|
your task.
|
|
136
137
|
{{else}}
|
|
137
138
|
This project has no AGENTS.md, the manual for a Uniweb project. Write one with
|
|
138
|
-
`npx uniweb update --agents-only`, then read
|
|
139
|
-
|
|
139
|
+
`npx uniweb update --agents-only`, then read it before writing code, and follow its
|
|
140
|
+
procedure.
|
|
140
141
|
{{/if}}
|
|
141
142
|
|
|
142
143
|
Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
|
package/src/commands/add.js
CHANGED
|
@@ -1451,6 +1451,8 @@ export default function ${name}({ content, params }) {
|
|
|
1451
1451
|
`${colors.dim}The dev server will pick it up automatically.${colors.reset}`
|
|
1452
1452
|
)
|
|
1453
1453
|
}
|
|
1454
|
+
log('')
|
|
1455
|
+
log(`Before editing it: ${colors.cyan}${getCliPrefix()} guide foundation${colors.reset}`)
|
|
1454
1456
|
|
|
1455
1457
|
if (starterResult) {
|
|
1456
1458
|
// Regenerate against the declaration just written, so what is printed is
|
package/src/commands/build.js
CHANGED
|
@@ -11,9 +11,10 @@
|
|
|
11
11
|
*
|
|
12
12
|
* --bundle (internal; called by `uniweb deploy --host` / `uniweb export`)
|
|
13
13
|
* Full vite + post-vite pipeline. Produces a static-host JS bundle
|
|
14
|
-
* (`dist/index.html`, `dist/
|
|
15
|
-
*
|
|
16
|
-
*
|
|
14
|
+
* (`dist/index.html`, the JS and CSS in `dist/assets/`, `_importmap/*` when
|
|
15
|
+
* a foundation or an extension loads by URL, `_pages/*` for split mode,
|
|
16
|
+
* sitemap/robots, each language's search index, llms.txt and page
|
|
17
|
+
* markdown, prerendered HTML when configured). The foundation is
|
|
17
18
|
* statically inlined when site.yml names a
|
|
18
19
|
* workspace-local one (the self-contained case), and loaded by URL when
|
|
19
20
|
* it names a URL, or under VITE_FOUNDATION_MODE=runtime. A catalog ref
|
|
@@ -691,12 +692,13 @@ async function buildSite(projectDir, options = {}) {
|
|
|
691
692
|
|
|
692
693
|
reportLocalizedSite(built)
|
|
693
694
|
} catch (err) {
|
|
694
|
-
|
|
695
|
+
// ⛔ Until 2026-11-02 this said "Continuing without localized content" and the build ended
|
|
696
|
+
// complete and exit 0, with every page of every other language missing.
|
|
697
|
+
error(`Couldn't build the site's other languages: ${err.message}`)
|
|
695
698
|
if (process.env.UNIWEB_DEBUG) {
|
|
696
699
|
console.error(err.stack)
|
|
697
700
|
}
|
|
698
|
-
|
|
699
|
-
log(`${colors.yellow}Continuing without localized content${colors.reset}`)
|
|
701
|
+
process.exit(1)
|
|
700
702
|
}
|
|
701
703
|
}
|
|
702
704
|
|
|
@@ -720,6 +722,11 @@ async function buildSite(projectDir, options = {}) {
|
|
|
720
722
|
success(
|
|
721
723
|
`Pre-rendered ${result.pages} page${result.pages !== 1 ? 's' : ''} to static HTML`
|
|
722
724
|
)
|
|
725
|
+
if (result.skipped?.length > 0) {
|
|
726
|
+
log(
|
|
727
|
+
`${colors.yellow}${result.skipped.length} page${result.skipped.length !== 1 ? 's' : ''} left to render in the browser: ${result.skipped.join(', ')}${colors.reset}`
|
|
728
|
+
)
|
|
729
|
+
}
|
|
723
730
|
|
|
724
731
|
// Summary
|
|
725
732
|
log('')
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `uniweb guide` — the part of a project's manual that isn't in its AGENTS.md.
|
|
3
|
+
*
|
|
4
|
+
* AGENTS.md holds what an agent would confidently get wrong, and each guide holds the rest of a
|
|
5
|
+
* subject, one command away. They ship in this package (`partials/guides/`), so what a project's
|
|
6
|
+
* CLI prints describes the code in that project's `node_modules`, and nothing is added to the
|
|
7
|
+
* project.
|
|
8
|
+
*
|
|
9
|
+
* ⭐ FOR AN AGENT, SO THE TEXT IS ALL THERE IS. The file goes to stdout as it is: no banner, no
|
|
10
|
+
* color, no pager. `--path` names the file, for a tool that cuts long output.
|
|
11
|
+
*
|
|
12
|
+
* ⛔ READ-ONLY, AND SAFE ANYWHERE. No network, no project files and no cache, so it also works in
|
|
13
|
+
* an empty folder (`npx uniweb@latest guide start`). `index.js` answers it before the update
|
|
14
|
+
* check, as it does `start`. Unlike `start` it is delegated to a project's own CLI, because the
|
|
15
|
+
* guide has to match the version the project pins.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { readFileSync } from 'node:fs'
|
|
19
|
+
import { dirname, join } from 'node:path'
|
|
20
|
+
import { fileURLToPath } from 'node:url'
|
|
21
|
+
import { didYouMean } from '../utils/args.js'
|
|
22
|
+
import { checkFlags } from '../utils/flag-guard.js'
|
|
23
|
+
|
|
24
|
+
const GUIDES_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'partials', 'guides')
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The guides, in the order `uniweb guide` lists them.
|
|
28
|
+
*
|
|
29
|
+
* @returns {Array<{ name: string, title: string, description: string }>}
|
|
30
|
+
*/
|
|
31
|
+
export function listGuides() {
|
|
32
|
+
return JSON.parse(readFileSync(join(GUIDES_DIR, 'index.json'), 'utf8'))
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Where a guide's file is. */
|
|
36
|
+
export function guidePath(name) {
|
|
37
|
+
return join(GUIDES_DIR, `${name}.md`)
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* What a guide's name was probably meant to be, and every name there is, for a name that isn't one.
|
|
42
|
+
*
|
|
43
|
+
* @param {string} name
|
|
44
|
+
* @param {string[]} names
|
|
45
|
+
* @returns {string}
|
|
46
|
+
*/
|
|
47
|
+
function unknownGuide(name, names) {
|
|
48
|
+
const near = didYouMean(name, names)
|
|
49
|
+
return [
|
|
50
|
+
`No guide named \`${name}\`.${near ? ` Did you mean \`${near}\`?` : ''}`,
|
|
51
|
+
` Guides: ${names.join(', ')}`,
|
|
52
|
+
].join('\n')
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* @param {string[]} [args] - guide names, and `--path`
|
|
57
|
+
* @returns {Promise<{ exitCode: number }>}
|
|
58
|
+
*/
|
|
59
|
+
export async function guide(args = []) {
|
|
60
|
+
const badFlag = checkFlags('guide', args)
|
|
61
|
+
if (badFlag) {
|
|
62
|
+
console.error(badFlag.message)
|
|
63
|
+
return { exitCode: 2 }
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
const guides = listGuides()
|
|
67
|
+
const asked = args.filter((arg) => !arg.startsWith('-'))
|
|
68
|
+
|
|
69
|
+
if (asked.length === 0) {
|
|
70
|
+
const width = Math.max(...guides.map((g) => g.name.length))
|
|
71
|
+
for (const g of guides) console.log(`${g.name.padEnd(width)} ${g.description}`)
|
|
72
|
+
return { exitCode: 0 }
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const names = guides.map((g) => g.name)
|
|
76
|
+
const unknown = asked.find((name) => !names.includes(name))
|
|
77
|
+
if (unknown) {
|
|
78
|
+
console.error(unknownGuide(unknown, names))
|
|
79
|
+
return { exitCode: 1 }
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
if (args.includes('--path')) {
|
|
83
|
+
for (const name of asked) console.log(guidePath(name))
|
|
84
|
+
return { exitCode: 0 }
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
process.stdout.write(asked.map((name) => readFileSync(guidePath(name), 'utf8').trimEnd()).join('\n\n---\n\n') + '\n')
|
|
88
|
+
return { exitCode: 0 }
|
|
89
|
+
}
|
package/src/commands/publish.js
CHANGED
|
@@ -168,6 +168,16 @@ function readSiteYml(path) {
|
|
|
168
168
|
}
|
|
169
169
|
}
|
|
170
170
|
|
|
171
|
+
// The backend's own sentences about a publish, for the person: what it changed (`applied`, a
|
|
172
|
+
// confirmed change or a reduction), then what it did not change and they should know (`notes`),
|
|
173
|
+
// such as something asked for that this deployment does not serve. The publish went through, so
|
|
174
|
+
// nothing else would say so.
|
|
175
|
+
export function publishSentences(result) {
|
|
176
|
+
return [result?.applied, result?.notes]
|
|
177
|
+
.flatMap((list) => (Array.isArray(list) ? list : []))
|
|
178
|
+
.filter((line) => typeof line === 'string' && line)
|
|
179
|
+
}
|
|
180
|
+
|
|
171
181
|
// Languages from the BUILT site — the authority after a build: `config.languages` where
|
|
172
182
|
// the site declares them (three accepted shapes: 'en', { value, label }, { code, label }),
|
|
173
183
|
// else its default and each language the build produced (`dist/<locale>/site-content.json`).
|
|
@@ -1141,11 +1151,7 @@ export async function publish(args = []) {
|
|
|
1141
1151
|
say.ok(
|
|
1142
1152
|
`Published ${c.bold}${siteUuid}${c.reset}${result.status ? ` (${result.status})` : ''}`
|
|
1143
1153
|
)
|
|
1144
|
-
|
|
1145
|
-
// (`applied`, its §4A). Absent when nothing changed.
|
|
1146
|
-
for (const line of Array.isArray(result.applied) ? result.applied : []) {
|
|
1147
|
-
if (typeof line === 'string' && line) say.info(line)
|
|
1148
|
-
}
|
|
1154
|
+
for (const line of publishSentences(result)) say.info(line)
|
|
1149
1155
|
|
|
1150
1156
|
// ⛔ SAY IT WHEN A LANGUAGE ASKED FOR DID NOT GO OUT.
|
|
1151
1157
|
//
|
package/src/commands/status.js
CHANGED
|
@@ -904,6 +904,17 @@ async function foundationCheck(siteDir, siteYml, client) {
|
|
|
904
904
|
return { id: 'app.foundation', state: 'ok', summary: `The site pins the latest version of its foundation (${fndVersion}).` }
|
|
905
905
|
}
|
|
906
906
|
|
|
907
|
+
/**
|
|
908
|
+
* What moves a project to a newer Uniweb. `--yes` because an agent has no terminal to answer the
|
|
909
|
+
* prompt, and the docs are why it can't wait: they describe the latest release.
|
|
910
|
+
*/
|
|
911
|
+
const LATEST_UPDATE = {
|
|
912
|
+
step: 'update',
|
|
913
|
+
latest: true,
|
|
914
|
+
command: 'npx uniweb@latest update --yes',
|
|
915
|
+
why: 'bring the project and its AGENTS.md up to date, since the docs describe the latest release — then build, and look at the pages'
|
|
916
|
+
}
|
|
917
|
+
|
|
907
918
|
/** `uniweb.version`: a newer Uniweb, named the same way for every release. */
|
|
908
919
|
async function versionCheck(siteDir, { offline }) {
|
|
909
920
|
const runs = projectUniweb(siteDir)
|
|
@@ -915,7 +926,7 @@ async function versionCheck(siteDir, { offline }) {
|
|
|
915
926
|
}
|
|
916
927
|
return {
|
|
917
928
|
checks: [{ id: 'uniweb.version', state: 'attention', summary: `Uniweb ${latest} is out; this project runs ${runs}.`, detail: { runs, latest } }],
|
|
918
|
-
proposals: [
|
|
929
|
+
proposals: [LATEST_UPDATE]
|
|
919
930
|
}
|
|
920
931
|
}
|
|
921
932
|
|
|
@@ -944,7 +955,7 @@ async function doctorCheck(siteDir) {
|
|
|
944
955
|
const newer = isBehind(projectUniweb(siteDir), getCliVersion())
|
|
945
956
|
proposals.push(
|
|
946
957
|
newer
|
|
947
|
-
?
|
|
958
|
+
? LATEST_UPDATE
|
|
948
959
|
: { step: 'update', command: 'npx uniweb update', why: "align the dependencies and AGENTS.md with this project's Uniweb" }
|
|
949
960
|
)
|
|
950
961
|
}
|
|
@@ -1384,6 +1395,14 @@ function workflowsCheck(siteDir) {
|
|
|
1384
1395
|
|
|
1385
1396
|
const list = (names) => names.map((n) => `\`${n}\``).join(', ')
|
|
1386
1397
|
|
|
1398
|
+
/**
|
|
1399
|
+
* Asked for, and never among what a publish reports delivering (`last_published_services`):
|
|
1400
|
+
* a host loads Google's tag, so nothing answers at an address and nothing is sold. By that
|
|
1401
|
+
* comparison it would read "not live yet" for ever, and send an agent back to publish. A row
|
|
1402
|
+
* changed since the last publish still says so, as `draft_dirty`.
|
|
1403
|
+
*/
|
|
1404
|
+
const NOT_REPORTED_AS_LIVE = new Set(['google'])
|
|
1405
|
+
|
|
1387
1406
|
/**
|
|
1388
1407
|
* `app.services`: what `site.yml` asks for, beside what the backend holds — the request it
|
|
1389
1408
|
* stored, and what the last publish delivered (`last_published_services`). Comparing the
|
|
@@ -1421,7 +1440,7 @@ async function servicesCheck({ siteDir, siteYml, site }) {
|
|
|
1421
1440
|
}
|
|
1422
1441
|
const live = on(site.last_published_services)
|
|
1423
1442
|
const requested = on(site.services)
|
|
1424
|
-
const waiting = requested.filter((n) => !live.includes(n))
|
|
1443
|
+
const waiting = requested.filter((n) => !live.includes(n) && !NOT_REPORTED_AS_LIVE.has(n))
|
|
1425
1444
|
if (waiting.length && site.published) {
|
|
1426
1445
|
lines.push(`Requested, not live yet: ${list(waiting)} — publishing makes ${waiting.length === 1 ? 'it' : 'them'} live, and may ask for payment.`)
|
|
1427
1446
|
proposals.push({ step: 'publish', command: 'npx uniweb publish', why: 'make those changes live — the person decides', ask: true })
|
|
@@ -1481,7 +1500,7 @@ const ICON = {
|
|
|
1481
1500
|
skipped: `${c.dim}·${c.reset}`
|
|
1482
1501
|
}
|
|
1483
1502
|
|
|
1484
|
-
function render({ summary, backend, checks, next }) {
|
|
1503
|
+
function render({ summary, backend, checks, next, neverShipped }) {
|
|
1485
1504
|
const out = ['']
|
|
1486
1505
|
out.push(`${c.bold}${summary}${c.reset}`)
|
|
1487
1506
|
for (const [prefix, title] of GROUPS) {
|
|
@@ -1512,6 +1531,10 @@ function render({ summary, backend, checks, next }) {
|
|
|
1512
1531
|
}
|
|
1513
1532
|
})
|
|
1514
1533
|
}
|
|
1534
|
+
if (neverShipped) {
|
|
1535
|
+
out.push('')
|
|
1536
|
+
out.push(`First time shipping this project? ${c.cyan}npx uniweb guide ship${c.reset}`)
|
|
1537
|
+
}
|
|
1515
1538
|
const unknown = checks.filter((k) => k.state === 'unknown').map((k) => k.id)
|
|
1516
1539
|
if (unknown.length) {
|
|
1517
1540
|
out.push('')
|
|
@@ -1700,7 +1723,9 @@ export async function status(args = []) {
|
|
|
1700
1723
|
)
|
|
1701
1724
|
return { exitCode: 0 }
|
|
1702
1725
|
}
|
|
1703
|
-
|
|
1726
|
+
// Nowhere yet: no site on a backend and no deploy on a host.
|
|
1727
|
+
const neverShipped = !synced.length && !deploys.targets.some((t) => t.deployed)
|
|
1728
|
+
console.log(render({ summary, backend: app.backend, checks, next, neverShipped }))
|
|
1704
1729
|
return { exitCode: 0 }
|
|
1705
1730
|
}
|
|
1706
1731
|
|
package/src/framework-index.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
|
-
"generatedAt": "2026-11-
|
|
3
|
+
"generatedAt": "2026-11-02T16:57:17.019Z",
|
|
4
4
|
"packages": {
|
|
5
5
|
"@uniweb/api": {
|
|
6
6
|
"version": "1.6.9"
|
|
7
7
|
},
|
|
8
8
|
"@uniweb/build": {
|
|
9
|
-
"version": "1.14.
|
|
9
|
+
"version": "1.14.2"
|
|
10
10
|
},
|
|
11
11
|
"@uniweb/content-reader": {
|
|
12
12
|
"version": "1.5.8"
|
|
@@ -24,10 +24,10 @@
|
|
|
24
24
|
"version": "1.0.8"
|
|
25
25
|
},
|
|
26
26
|
"@uniweb/kit": {
|
|
27
|
-
"version": "1.7.
|
|
27
|
+
"version": "1.7.2"
|
|
28
28
|
},
|
|
29
29
|
"@uniweb/loom": {
|
|
30
|
-
"version": "1.1.
|
|
30
|
+
"version": "1.1.3"
|
|
31
31
|
},
|
|
32
32
|
"@uniweb/press": {
|
|
33
33
|
"version": "1.2.1"
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"version": "1.2.10"
|
|
37
37
|
},
|
|
38
38
|
"@uniweb/runtime": {
|
|
39
|
-
"version": "1.3.
|
|
39
|
+
"version": "1.3.12"
|
|
40
40
|
},
|
|
41
41
|
"@uniweb/scene": {
|
|
42
42
|
"version": "1.0.1"
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"version": "1.1.2"
|
|
55
55
|
},
|
|
56
56
|
"@uniweb/templates": {
|
|
57
|
-
"version": "1.2.
|
|
57
|
+
"version": "1.2.2"
|
|
58
58
|
},
|
|
59
59
|
"@uniweb/theming": {
|
|
60
60
|
"version": "1.2.1"
|
package/src/index.js
CHANGED
|
@@ -721,6 +721,21 @@ async function main() {
|
|
|
721
721
|
return
|
|
722
722
|
}
|
|
723
723
|
|
|
724
|
+
// `guide` — the rest of a project's manual (commands/guide.js). Reached here from a project's
|
|
725
|
+
// own CLI, or with no project at all; like `start`, it asks nothing and makes no request. Its
|
|
726
|
+
// output is the file and nothing else, so the exit code is set rather than exited on, which
|
|
727
|
+
// would cut a long guide short on a pipe.
|
|
728
|
+
if (command === 'guide') {
|
|
729
|
+
if (args.slice(1).some((a) => a === '--help' || a === '-h')) {
|
|
730
|
+
printCommandHelp('guide')
|
|
731
|
+
return
|
|
732
|
+
}
|
|
733
|
+
const { guide } = await import('./commands/guide.js')
|
|
734
|
+
const { exitCode } = await guide(args.slice(1))
|
|
735
|
+
process.exitCode = exitCode
|
|
736
|
+
return
|
|
737
|
+
}
|
|
738
|
+
|
|
724
739
|
// Update check for global installs.
|
|
725
740
|
//
|
|
726
741
|
// - `create` / `clone` STOP when a newer release exists, before anything is
|
|
@@ -1437,7 +1452,7 @@ async function main() {
|
|
|
1437
1452
|
}
|
|
1438
1453
|
log('')
|
|
1439
1454
|
log(
|
|
1440
|
-
` ${colors.bright}AGENTS.md${colors.reset} is the project's manual, for you and for AI agents:
|
|
1455
|
+
` ${colors.bright}AGENTS.md${colors.reset} is the project's manual, for you and for AI agents: read it before you start.`
|
|
1441
1456
|
)
|
|
1442
1457
|
if (recPm !== 'pnpm') {
|
|
1443
1458
|
log('')
|
|
@@ -1595,6 +1610,20 @@ pay when the site goes live; the guide has the agent run every command.
|
|
|
1595
1610
|
Inside a Uniweb project it starts from that project instead of creating one.
|
|
1596
1611
|
It asks nothing, writes nothing and makes no request, so it is safe to run
|
|
1597
1612
|
anywhere. To run a site's dev server, use \`uniweb dev\`.
|
|
1613
|
+
`,
|
|
1614
|
+
guide: `
|
|
1615
|
+
${colors.cyan}${colors.bright}uniweb guide${colors.reset} ${colors.dim}— The rest of a project's manual, one subject at a time${colors.reset}
|
|
1616
|
+
|
|
1617
|
+
${colors.bright}Usage:${colors.reset}
|
|
1618
|
+
uniweb guide List the guides
|
|
1619
|
+
uniweb guide <name> Print a guide, in Markdown
|
|
1620
|
+
uniweb guide <name> <name> Print several
|
|
1621
|
+
uniweb guide <name> --path Print where its file is, to read instead
|
|
1622
|
+
|
|
1623
|
+
AGENTS.md holds what an agent would otherwise get wrong, and tells it which guide
|
|
1624
|
+
to run for a task. The guides ship with the CLI, so in a project they describe the
|
|
1625
|
+
version the project pins. They need no network and no project, so
|
|
1626
|
+
\`npx uniweb@latest guide start\` works in an empty folder.
|
|
1598
1627
|
`,
|
|
1599
1628
|
dev: `
|
|
1600
1629
|
${colors.cyan}${colors.bright}uniweb dev${colors.reset} ${colors.dim}— Start a dev server for a site${colors.reset}
|
|
@@ -2343,6 +2372,7 @@ ${colors.bright}Usage:${colors.reset}
|
|
|
2343
2372
|
|
|
2344
2373
|
${colors.bright}Commands:${colors.reset}
|
|
2345
2374
|
start How an AI agent begins a site (a guide; changes nothing)
|
|
2375
|
+
guide [name] Print a guide to building with Uniweb: content, foundation, theme, …
|
|
2346
2376
|
create [name] Create a new project
|
|
2347
2377
|
clone <site-uuid> Clone a backend site into a local file project
|
|
2348
2378
|
add <type> [name] Add a foundation, site, or extension to a project
|
|
@@ -31,13 +31,28 @@ export function readAgentsVersion(filePath) {
|
|
|
31
31
|
}
|
|
32
32
|
|
|
33
33
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
34
|
+
* ⭐ THE LAST LINE OF EVERY AGENTS.md, after any project notes. A tool may cut an instruction file
|
|
35
|
+
* without saying so: Codex stops at `project_doc_max_bytes`, 32 KiB by default, counting every
|
|
36
|
+
* instruction file it has read, and a person can raise that. So the file doesn't promise to fit
|
|
37
|
+
* [Diego, 2026-11-02]. It says near its top, inside any cap, that this line ends it, and an agent
|
|
38
|
+
* that can't see the line reads the rest itself.
|
|
36
39
|
*/
|
|
37
|
-
export
|
|
40
|
+
export const AGENTS_END_LINE = 'End of AGENTS.md'
|
|
41
|
+
|
|
42
|
+
/** The partial, stamped, with nothing after it. */
|
|
43
|
+
function stampedPartial() {
|
|
38
44
|
const partialsDir = join(__dirname, '..', '..', 'partials')
|
|
39
45
|
const agentsContent = readFileSync(join(partialsDir, 'agents.md'), 'utf8')
|
|
40
|
-
return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent}
|
|
46
|
+
return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent.trimEnd()}`
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Generate AGENTS.md content with version stamp: what `create` writes, and what `update` writes
|
|
51
|
+
* for a project with no notes.
|
|
52
|
+
* @returns {string} Full AGENTS.md content with stamp
|
|
53
|
+
*/
|
|
54
|
+
export function generateAgentsContent() {
|
|
55
|
+
return `${stampedPartial()}\n\n${AGENTS_END_LINE}\n`
|
|
41
56
|
}
|
|
42
57
|
|
|
43
58
|
/**
|
|
@@ -91,20 +106,19 @@ export function readProjectNotes(text) {
|
|
|
91
106
|
}
|
|
92
107
|
|
|
93
108
|
/**
|
|
94
|
-
* AGENTS.md as `update` writes it: this CLI's partial, stamped,
|
|
95
|
-
* file it replaces after it.
|
|
109
|
+
* AGENTS.md as `update` writes it: this CLI's partial, stamped, the project-notes blocks of the
|
|
110
|
+
* file it replaces after it, and the line that ends the file.
|
|
96
111
|
*
|
|
97
112
|
* @param {string|null} existing - the current AGENTS.md, or null when there is none
|
|
98
113
|
* @returns {{ content: string, kept: number } | { error: string }}
|
|
99
114
|
*/
|
|
100
115
|
export function refreshAgentsContent(existing) {
|
|
101
|
-
|
|
102
|
-
if (existing == null) return { content: fresh, kept: 0 }
|
|
116
|
+
if (existing == null) return { content: generateAgentsContent(), kept: 0 }
|
|
103
117
|
const notes = readProjectNotes(existing)
|
|
104
118
|
if (notes.error) return notes
|
|
105
|
-
if (!notes.blocks.length) return { content:
|
|
119
|
+
if (!notes.blocks.length) return { content: generateAgentsContent(), kept: 0 }
|
|
106
120
|
return {
|
|
107
|
-
content: `${
|
|
121
|
+
content: `${stampedPartial()}\n\n${notes.blocks.join('\n\n')}\n\n${AGENTS_END_LINE}\n`,
|
|
108
122
|
kept: notes.blocks.length,
|
|
109
123
|
}
|
|
110
124
|
}
|
package/src/utils/flag-guard.js
CHANGED
|
@@ -142,7 +142,9 @@ const VERBS = {
|
|
|
142
142
|
* `flag-guard-coverage.test.js`'s walk does not see it). ⛔ Until 2026-10-25 `dev` checked
|
|
143
143
|
* no flags, and read the value of `--port 5199` as the name of a site.
|
|
144
144
|
*/
|
|
145
|
-
dev: ['--site', '--port', '--status', '--stop', '--org', '--personal']
|
|
145
|
+
dev: ['--site', '--port', '--status', '--stop', '--org', '--personal'],
|
|
146
|
+
// Prints a file: a flag it doesn't know is a typo, not a backend it might reach.
|
|
147
|
+
guide: ['--path']
|
|
146
148
|
}
|
|
147
149
|
|
|
148
150
|
/**
|
package/src/utils/scaffold.js
CHANGED
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
} from '../templates/processor.js'
|
|
19
19
|
import { getVersionsForTemplates, getCliVersion } from '../versions.js'
|
|
20
20
|
import { writeJsonPreservingStyleAsync } from './json-file.js'
|
|
21
|
+
import { generateAgentsContent } from './agents-stamp.js'
|
|
21
22
|
|
|
22
23
|
const __dirname = dirname(fileURLToPath(import.meta.url))
|
|
23
24
|
const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates')
|
|
@@ -46,8 +47,8 @@ export async function scaffoldWorkspace(targetDir, context, options = {}) {
|
|
|
46
47
|
// because an empty packages: [] makes pnpm search parent directories.
|
|
47
48
|
const skip = context.workspaceGlobs?.length ? [] : ['pnpm-workspace.yaml']
|
|
48
49
|
|
|
49
|
-
//
|
|
50
|
-
context = { ...context, cliVersion: getCliVersion() }
|
|
50
|
+
// AGENTS.md comes from the one writer `update` uses too, so `create` and `update` can't differ.
|
|
51
|
+
context = { ...context, cliVersion: getCliVersion(), agentsContent: generateAgentsContent() }
|
|
51
52
|
|
|
52
53
|
const templatePath = join(TEMPLATES_DIR, 'workspace')
|
|
53
54
|
await copyTemplateDirectory(templatePath, targetDir, context, {
|
|
@@ -1,2 +1 @@
|
|
|
1
|
-
|
|
2
|
-
{{> agents}}
|
|
1
|
+
{{{agentsContent}}}
|
|
@@ -133,7 +133,8 @@ conventions, instead of a blank canvas. What an agent builds here, authors can u
|
|
|
133
133
|
after the next sync.
|
|
134
134
|
|
|
135
135
|
[AGENTS.md](./AGENTS.md) is written for developers and AI agents alike. Many coding agents read it
|
|
136
|
-
on their own when they start in this folder; point any other agent at it first.
|
|
136
|
+
on their own when they start in this folder; point any other agent at it first. `npx uniweb guide`
|
|
137
|
+
prints the rest of the manual, one subject at a time.
|
|
137
138
|
`npx uniweb@latest update` moves the project to the latest release of Uniweb, and AGENTS.md with
|
|
138
139
|
it.
|
|
139
140
|
|