uniweb 1.25.4 → 1.25.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/README.md +1 -0
- package/package.json +6 -6
- package/partials/agents.md +247 -3174
- package/partials/guides/backend.md +155 -0
- package/partials/guides/content.md +314 -0
- package/partials/guides/data.md +216 -0
- package/partials/guides/foundation.md +339 -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 +176 -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/export.js +4 -3
- package/src/commands/guide.js +89 -0
- package/src/commands/publish.js +6 -5
- package/src/commands/push.js +8 -6
- package/src/commands/status.js +21 -4
- package/src/framework-index.json +7 -7
- 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
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Theming: tokens, light and dark, `theme.yml`, fonts, `styles.css`
|
|
2
|
+
|
|
3
|
+
On-demand guide (`uniweb guide theme`); AGENTS.md is assumed read. Author's view: `reference/site-theming.md`.
|
|
4
|
+
|
|
5
|
+
## Semantic tokens
|
|
6
|
+
|
|
7
|
+
| Token | Purpose |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `heading`, `body`, `subtle` | text |
|
|
10
|
+
| `section`, `card`, `muted` | section background, panel background, hover/zebra |
|
|
11
|
+
| `border`, `ring` | lines, focus |
|
|
12
|
+
| `link` / `link-hover` | links |
|
|
13
|
+
| `primary` / `-foreground` / `-hover` / `-border`, `secondary` / … | actions |
|
|
14
|
+
| `success` / `warning` / `error` / `info`, `+ -subtle` | status, status backgrounds |
|
|
15
|
+
|
|
16
|
+
Palette shades: `text-primary-600`, `bg-neutral-100`, `border-accent-300` — 50–950 for primary, secondary, accent, neutral. Full mapping in `theme-tokens.css`.
|
|
17
|
+
|
|
18
|
+
**Debugging a token that "does nothing" — don't probe in the browser.** Tailwind v4 is JIT and emits only classes found in scanned source, so a class assigned from the console can never resolve. Ask the build: `grep -o '\.text-link{[^}]*}' dist/assets/*.css`. A rule prints → the utility exists and something overrides it at runtime. Nothing prints → `styles.css` doesn't import `theme-tokens.css` (or declares its own `@theme inline` omitting it), or `@source` doesn't cover the file.
|
|
19
|
+
|
|
20
|
+
**Per-section theme maps.** A section's `theme:` is `theme.yml` for that section — tokens beside `mode`, plus `colors`, `contexts`, `vars` scoped to it (`theme: { mode: light, section: neutral-100, card: neutral-50, primary: neutral-900, colors: { accent: '#e65100' }, contexts: { dark: { link: accent-300 } } }`). `background:` accepts CSS variables and hex too, so authors alternate surfaces with no component code. Map a source design's surface variations to backgrounds or token overrides in frontmatter — not to component code.
|
|
21
|
+
|
|
22
|
+
## Section context vs site scheme
|
|
23
|
+
|
|
24
|
+
- **Section context** — `theme:` on one section. Per-section, author-controlled.
|
|
25
|
+
- **Site scheme** — the global preference under `appearance:` in `theme.yml`; the visitor's toggle.
|
|
26
|
+
|
|
27
|
+
A section with no `theme:` follows the scheme; one that pins `theme: dark` stays dark in either.
|
|
28
|
+
|
|
29
|
+
```yaml
|
|
30
|
+
appearance:
|
|
31
|
+
default: light # light | dark | system
|
|
32
|
+
allowToggle: true # offer a switch (also generates dark tokens)
|
|
33
|
+
respectSystemPreference: true # first visit follows the OS; false pins `default`
|
|
34
|
+
schemes: [light, dark]
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Shorthands: `appearance: light` / `dark` (fixed), `appearance: system`. A site has dark mode when it offers a toggle, defaults to `dark`/`system`, or lists `dark`. Precedence: stored choice > a dark OS > `default:` — the OS can only choose dark, so `default: light` is a fallback, not a guarantee, unless `respectSystemPreference: false`, and `default: dark` stays dark on a light OS.
|
|
38
|
+
|
|
39
|
+
| Goal | `theme.yml` |
|
|
40
|
+
|---|---|
|
|
41
|
+
| Always light / dark, no switch | `appearance: light` / `dark` |
|
|
42
|
+
| Toggle, follow OS on first visit | `{ default: system, allowToggle: true }` |
|
|
43
|
+
| Toggle, always start light | `{ default: light, allowToggle: true, respectSystemPreference: false }` |
|
|
44
|
+
|
|
45
|
+
```jsx
|
|
46
|
+
const { scheme, toggle, canToggle } = useAppearance()
|
|
47
|
+
if (!canToggle) return null
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The runtime applies `scheme-dark`/`scheme-light` to `<html>` before paint. For Tailwind `dark:` utilities: `@custom-variant dark (&:where(.scheme-dark, .scheme-dark *));` in `styles.css`; prefer tokens, which adapt per section.
|
|
51
|
+
|
|
52
|
+
## theme.yml
|
|
53
|
+
|
|
54
|
+
```yaml
|
|
55
|
+
colors:
|
|
56
|
+
primary: '#3b82f6' # your hex at shade 500
|
|
57
|
+
secondary: '#64748b'
|
|
58
|
+
accent: '#8b5cf6'
|
|
59
|
+
neutral: stone # named preset: stone, zinc, gray, slate, neutral
|
|
60
|
+
contexts:
|
|
61
|
+
light: { section: '#fafaf9' }
|
|
62
|
+
appearance: { default: light, allowToggle: true }
|
|
63
|
+
fonts: { heading: "'Inter', system-ui, sans-serif", body: "'Inter', system-ui, sans-serif" }
|
|
64
|
+
inline: { callout: { color: var(--accent), font-weight: '600' } }
|
|
65
|
+
vars: { radius: 0.75rem }
|
|
66
|
+
code: dracula # or { light: github-light, dark: github-dark }, or { theme: github-dark, background: '#0D0D0D' }
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Context override keys match token names (`section:` not `bg:`). In light/medium `--primary` uses shade 600, `--link` 600, `--ring` 500; in dark `--primary` 500, `--link` 400. Buttons use 600 for contrast with white text; for brand-exact buttons set `contexts.light.primary: primary-500` and `primary-hover: primary-600`, and test contrast — bright brands at 500 may fail WCAG 4.5:1. A code block paints its theme's background and foreground before the highlighter loads when both are known.
|
|
70
|
+
|
|
71
|
+
## Fonts
|
|
72
|
+
|
|
73
|
+
| Role | Wired onto | Use |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `body` | `body` | paragraphs, UI |
|
|
76
|
+
| `heading` | `h1, h2, h3` | titles |
|
|
77
|
+
| `code` | `code, pre, kbd, samp` | monospace |
|
|
78
|
+
|
|
79
|
+
The site wires families onto elements, so a foundation normally sets none — render semantic markup and the roles apply. Weight/size/style utilities are yours; a font-**family** utility (`font-sans`, `font-serif`) resolves to Tailwind's stacks unless the foundation declares it as a font var. For typefaces the three roles can't express, declare each as a **font var** in `main.js` — a `font-*` name is recognised as a typeface (a bare name takes `type: 'font'`):
|
|
80
|
+
|
|
81
|
+
```js
|
|
82
|
+
export const vars = {
|
|
83
|
+
'font-serif': { default: 'ui-serif, Georgia, serif', applyTo: ['blockquote', '.tagline'] }, // framework emits the rule
|
|
84
|
+
'font-display': { default: 'ui-sans-serif, system-ui, sans-serif' }, // component wires it
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`fonts:` in `theme.yml` takes any role name; redeclaring a built-in role's var with a new `applyTo` retargets it. `serif` and `font-serif` are the same var (the site sets it by the bare role name).
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
fonts:
|
|
92
|
+
heading: "Poppins, sans-serif"
|
|
93
|
+
serif: '"Fraunces", Georgia, serif'
|
|
94
|
+
import: [{ url: "https://fonts.googleapis.com/css2?family=Poppins:wght@600;700" }]
|
|
95
|
+
faces: [{ family: "Fraunces", src: /fonts/fraunces.woff2, weight: "100 900" }]
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The build adds preconnect hints, emits `@font-face` + preload, drops unreferenced families; `uniweb push` uploads face files under `public/`. An imported font replaces the fallback when it arrives (`display=swap`, unless the URL says otherwise), which can re-wrap text on a first visit. `display=optional` in the URL keeps the font first drawn for that visit instead, and `faces:` serves the files from the site, preloaded. The `code` role owns `--font-code`; Tailwind's `font-mono` reads `--font-mono`, a separate var you declare yourself. A role's face on an element it isn't wired onto — a wordmark in the heading face, say — is `font-family: var(--font-heading)`, or a utility of your own: `@theme inline { --font-display: var(--font-heading); }` in `styles.css`, then `font-display`.
|
|
99
|
+
|
|
100
|
+
## styles.css
|
|
101
|
+
|
|
102
|
+
```css
|
|
103
|
+
@import "tailwindcss";
|
|
104
|
+
@import "@uniweb/kit/theme-tokens.css";
|
|
105
|
+
@import "@uniweb/kit/prose-tokens.css";
|
|
106
|
+
@source "./sections/**/*.{js,jsx}";
|
|
107
|
+
@source "./components/**/*.{js,jsx}";
|
|
108
|
+
@source "./layouts/**/*.{js,jsx}";
|
|
109
|
+
@theme { --breakpoint-xs: 30rem; }
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Two more imports are opt-in: `@uniweb/kit/math-tokens.css` lays out equations, and `@uniweb/kit/callout-tokens.css` draws concept blocks such as `md:warning`, which are otherwise plain prose.
|
|
113
|
+
|
|
114
|
+
**Name every folder that writes classes.** The foundation's own build finds them all, but a site build and `uniweb dev` read only what these lines name, so a class in a folder left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) give the line to add. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
|
|
115
|
+
|
|
116
|
+
Custom CSS is expected alongside Tailwind — shadow systems, border hierarchies, gradients, glass. Tokens are a floor; add vocabulary that references them so it adapts per context:
|
|
117
|
+
|
|
118
|
+
```css
|
|
119
|
+
.border-subtle { border-color: color-mix(in oklch, var(--border), transparent 50%); }
|
|
120
|
+
.text-tertiary { color: color-mix(in oklch, var(--body), var(--subtle) 50%); }
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Priority: design quality > portability > configurability. Four things a ported design brings that break something: global `scroll-behavior: smooth` (the runtime's `scrollTo(x, y)` inherits it and route changes animate/interrupt — scope it to an element); `filter: blur()` glows (Safari repaints them on the main thread during view transitions — use a radial `mask-image` instead); `-webkit-font-smoothing: antialiased` on `html` (scope it to `.scheme-dark`); JS-started entrance animations (write them in CSS so they start at first paint on a prerendered page).
|
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('')
|
package/src/commands/export.js
CHANGED
|
@@ -6,9 +6,10 @@
|
|
|
6
6
|
* CloudFront, etc.). Does NOT upload anywhere — `uniweb deploy --host`
|
|
7
7
|
* uploads to a third-party host; `uniweb publish` ships to Uniweb hosting.
|
|
8
8
|
*
|
|
9
|
-
* The `dist/` output
|
|
10
|
-
*
|
|
11
|
-
*
|
|
9
|
+
* The `dist/` output concatenates the runtime and a local foundation into the
|
|
10
|
+
* site's JS (a foundation named by URL stays a URL), with the content beside
|
|
11
|
+
* that JS and never in it: a vite-built `index.html` + `entry.js` + `assets/`.
|
|
12
|
+
* The user copies it to whatever host they like.
|
|
12
13
|
*
|
|
13
14
|
* Internally this is `uniweb build --bundle` plus user guidance for the
|
|
14
15
|
* upload step. The `--link` / `--bundle` flag pair is internal-only
|
|
@@ -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
|
@@ -679,10 +679,10 @@ export async function publish(args = []) {
|
|
|
679
679
|
reportSchemalessQueries(probe.schemaless, say)
|
|
680
680
|
const localAssets = probe.localAssets || []
|
|
681
681
|
|
|
682
|
-
// 3a. A
|
|
683
|
-
// that describes one is stale
|
|
684
|
-
//
|
|
685
|
-
// which mints a uuid and would make the
|
|
682
|
+
// 3a. A copy with no site uuid for this backend (`sync.json`) is bound to no site
|
|
683
|
+
// there, so every cached map that describes one is stale. `uniweb forget` clears
|
|
684
|
+
// the maps with the uuid; this catches a uuid gone any other way. Must run BEFORE
|
|
685
|
+
// the create, which mints a uuid and would make the copy look bound.
|
|
686
686
|
const droppedState = clearRemoteSyncStateIfUnbound(siteDir, client.origin)
|
|
687
687
|
if (droppedState.length) {
|
|
688
688
|
say.dim(
|
|
@@ -697,7 +697,8 @@ export async function publish(args = []) {
|
|
|
697
697
|
// so a repeatedly-failing first publish would burn quota with no recovery
|
|
698
698
|
// short of support. Creating the site first makes the artifact of a failed
|
|
699
699
|
// publish an EMPTY SITE instead: it costs nothing to keep and the owner can
|
|
700
|
-
// clear it. A no-op once
|
|
700
|
+
// clear it. A no-op once `sync.json` holds this backend's site uuid, so only
|
|
701
|
+
// a first publish pays.
|
|
701
702
|
//
|
|
702
703
|
// This ordering is load-bearing, not incidental — the asset plan requires an
|
|
703
704
|
// owner. A test asserts the create precedes the upload.
|
package/src/commands/push.js
CHANGED
|
@@ -348,11 +348,12 @@ export async function push(args = [], deps = {}) {
|
|
|
348
348
|
// ⛔ DROP STALE REMOTE STATE FIRST — this must precede the hash read below, and it
|
|
349
349
|
// did not until 2026-08-19.
|
|
350
350
|
//
|
|
351
|
-
// The guard itself is right and its docblock names this exact outcome: on a
|
|
352
|
-
// whose
|
|
353
|
-
//
|
|
354
|
-
// had not changed since the OLD site's last push,
|
|
355
|
-
// missing exactly the content that did not change."
|
|
351
|
+
// The guard itself is right and its docblock names this exact outcome: on a copy
|
|
352
|
+
// whose site uuid went without the maps — which our own guidance to clear `$uuid`
|
|
353
|
+
// led to, until 2026-09-21; `uniweb forget` takes both now — send-only-changed would
|
|
354
|
+
// "skip every entity whose content had not changed since the OLD site's last push,
|
|
355
|
+
// so the NEW site would come up missing exactly the content that did not change."
|
|
356
|
+
// It was defeated twice over:
|
|
356
357
|
//
|
|
357
358
|
// · it ran AFTER `readSyncCache`, so the emit still diffed against the old
|
|
358
359
|
// site's hashes even though the file on disk had just been emptied;
|
|
@@ -483,7 +484,8 @@ export async function push(args = [], deps = {}) {
|
|
|
483
484
|
if (mediaRefs.length) {
|
|
484
485
|
// The site has to exist before its bytes do — an upload with no owning
|
|
485
486
|
// entity is charged and cannot be freed, because freeing means deleting the
|
|
486
|
-
// owner. A no-op once
|
|
487
|
+
// owner. A no-op once `sync.json` holds this backend's site uuid, so only a
|
|
488
|
+
// never-synced site pays.
|
|
487
489
|
// ⛔ The PINNED ref, not site.yml's. The create is a THIRD writer of this
|
|
488
490
|
// value — the emit below stamps it via `injectInfo`, publish passes it here,
|
|
489
491
|
// and push did neither until 2026-08-19: it sent the authored alias (`src`),
|
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
|
}
|
|
@@ -1489,7 +1500,7 @@ const ICON = {
|
|
|
1489
1500
|
skipped: `${c.dim}·${c.reset}`
|
|
1490
1501
|
}
|
|
1491
1502
|
|
|
1492
|
-
function render({ summary, backend, checks, next }) {
|
|
1503
|
+
function render({ summary, backend, checks, next, neverShipped }) {
|
|
1493
1504
|
const out = ['']
|
|
1494
1505
|
out.push(`${c.bold}${summary}${c.reset}`)
|
|
1495
1506
|
for (const [prefix, title] of GROUPS) {
|
|
@@ -1520,6 +1531,10 @@ function render({ summary, backend, checks, next }) {
|
|
|
1520
1531
|
}
|
|
1521
1532
|
})
|
|
1522
1533
|
}
|
|
1534
|
+
if (neverShipped) {
|
|
1535
|
+
out.push('')
|
|
1536
|
+
out.push(`First time shipping this project? ${c.cyan}npx uniweb guide ship${c.reset}`)
|
|
1537
|
+
}
|
|
1523
1538
|
const unknown = checks.filter((k) => k.state === 'unknown').map((k) => k.id)
|
|
1524
1539
|
if (unknown.length) {
|
|
1525
1540
|
out.push('')
|
|
@@ -1708,7 +1723,9 @@ export async function status(args = []) {
|
|
|
1708
1723
|
)
|
|
1709
1724
|
return { exitCode: 0 }
|
|
1710
1725
|
}
|
|
1711
|
-
|
|
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 }))
|
|
1712
1729
|
return { exitCode: 0 }
|
|
1713
1730
|
}
|
|
1714
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-02T19:27:56.253Z",
|
|
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.3"
|
|
10
10
|
},
|
|
11
11
|
"@uniweb/content-reader": {
|
|
12
12
|
"version": "1.5.8"
|
|
@@ -24,19 +24,19 @@
|
|
|
24
24
|
"version": "1.0.8"
|
|
25
25
|
},
|
|
26
26
|
"@uniweb/kit": {
|
|
27
|
-
"version": "1.7.
|
|
27
|
+
"version": "1.7.3"
|
|
28
28
|
},
|
|
29
29
|
"@uniweb/loom": {
|
|
30
|
-
"version": "1.1.
|
|
30
|
+
"version": "1.1.3"
|
|
31
31
|
},
|
|
32
32
|
"@uniweb/press": {
|
|
33
|
-
"version": "1.2.
|
|
33
|
+
"version": "1.2.2"
|
|
34
34
|
},
|
|
35
35
|
"@uniweb/projections": {
|
|
36
36
|
"version": "1.2.10"
|
|
37
37
|
},
|
|
38
38
|
"@uniweb/runtime": {
|
|
39
|
-
"version": "1.3.
|
|
39
|
+
"version": "1.3.13"
|
|
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.3"
|
|
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
|
/**
|