uniweb 0.8.32 → 0.8.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.32",
+  "version": "0.8.34",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.5.18",
-    "@uniweb/kit": "0.7.21",
-    "@uniweb/runtime": "0.6.27"
+    "@uniweb/runtime": "0.6.29",
+    "@uniweb/core": "0.5.19",
+    "@uniweb/kit": "0.7.22"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.8.31",
     "@uniweb/content-reader": "1.1.4",
-    "@uniweb/semantic-parser": "1.1.8"
+    "@uniweb/semantic-parser": "1.1.9",
+    "@uniweb/build": "0.8.33"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -274,6 +274,23 @@ Programs offered                  │  content.items[1].paragraphs[0]
 
 Without the `---`, `## 15,000+` would become `content.subtitle` instead of an item.
 
+### Sequential content
+
+`content.sequence` is the flat, ordered list of all elements before any grouping. Each element has a `type` (`heading`, `paragraph`, `image`, `codeBlock`, `dataBlock`, `list`, `link`, `divider`, `inset`, etc.) and type-specific fields. Use it when grouping isn't the right lens — for example, rendering prose in document order with `<Prose>`, or finding specific elements regardless of which group they ended up in:
+
+```js
+// All data blocks, regardless of heading groups
+const allData = {}
+for (const el of content.sequence) {
+  if (el.type === 'dataBlock') allData[el.tag] = el.data
+}
+
+// All headings in order
+const headings = content.sequence.filter(e => e.type === 'heading')
+```
+
+The grouped fields (`title`, `paragraphs`, `items`, `data`) and the sequential view (`sequence`) are two interpretations of the same content. Grouped is better for structured layouts (cards, features). Sequential is better for prose rendering and for finding content without caring about group boundaries.
+
 ### Choosing how to model content
 
 You have three layers. Most of the design skill is choosing between them:

package/src/commands/doctor.js

@@ -5,6 +5,8 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join, resolve, basename, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
+import { getCliVersion } from '../versions.js'
+import { readAgentsVersion } from '../utils/agents-stamp.js'
 
 // ANSI colors
 const colors = {
@@ -484,6 +486,29 @@ export async function doctor(args = []) {
     }
   }
 
+  // Check AGENTS.md freshness
+  log('')
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const agentsVersion = readAgentsVersion(agentsPath)
+  const cliVersion = getCliVersion()
+
+  if (!existsSync(agentsPath)) {
+    warn('AGENTS.md not found')
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: 'AGENTS.md not found' })
+  } else if (!agentsVersion) {
+    // No stamp — manually created or pre-stamp version
+    warn('AGENTS.md has no version stamp (may be outdated)')
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: 'AGENTS.md has no version stamp' })
+  } else if (agentsVersion !== cliVersion) {
+    warn(`AGENTS.md is outdated (v${agentsVersion} → v${cliVersion})`)
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: `AGENTS.md outdated (v${agentsVersion} → v${cliVersion})` })
+  } else {
+    success(`AGENTS.md is up to date (v${cliVersion})`)
+  }
+
   // Summary
   log('')
   log('─'.repeat(50))

package/src/commands/update.js

@@ -0,0 +1,55 @@
+/**
+ * uniweb update - Update generated project files
+ *
+ * Regenerates AGENTS.md from the installed CLI version.
+ */
+
+import { existsSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import { readAgentsVersion, generateAgentsContent } from '../utils/agents-stamp.js'
+import { getCliVersion } from '../versions.js'
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m'
+}
+
+const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
+const log = console.log
+
+export async function update(args = []) {
+  const workspaceDir = findWorkspaceRoot(process.cwd())
+
+  if (!workspaceDir) {
+    error('Not in a Uniweb workspace')
+    log(`${colors.dim}Run this command from your project root or a package directory.${colors.reset}`)
+    process.exit(1)
+  }
+
+  const cliVersion = getCliVersion()
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const currentVersion = readAgentsVersion(agentsPath)
+
+  if (currentVersion === cliVersion) {
+    success(`AGENTS.md is already up to date (v${cliVersion})`)
+    return
+  }
+
+  const content = generateAgentsContent()
+  writeFileSync(agentsPath, content)
+
+  if (currentVersion) {
+    success(`Updated AGENTS.md (v${currentVersion} → v${cliVersion})`)
+  } else {
+    success(`Created AGENTS.md (v${cliVersion})`)
+  }
+}

package/src/index.js

@@ -35,6 +35,7 @@ import { publish } from './commands/publish.js'
 import { deploy } from './commands/deploy.js'
 import { invite } from './commands/invite.js'
 import { handoff } from './commands/handoff.js'
+import { update } from './commands/update.js'
 import { template } from './commands/template.js'
 import {
   resolveTemplate,
@@ -479,6 +480,12 @@ async function main() {
     return
   }
 
+  // Handle update command
+  if (command === 'update') {
+    await update(args.slice(1))
+    return
+  }
+
   // Handle inspect command
   if (command === 'inspect') {
     await inspect(args.slice(1))
@@ -794,6 +801,7 @@ ${colors.bright}Commands:${colors.reset}
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   doctor             Diagnose project configuration issues
+  update             Update AGENTS.md to match installed CLI version
   i18n <cmd>         Internationalization (extract, sync, status)
   template publish   Publish a site as a cloud template
   login              Log in to your Uniweb account

package/src/utils/agents-stamp.js

@@ -0,0 +1,41 @@
+/**
+ * AGENTS.md version stamp utilities
+ *
+ * The stamp is an HTML comment on the first line: <!-- uniweb-agents v0.8.32 -->
+ * Used by `doctor` (freshness check) and `update` (regeneration).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { getCliVersion } from '../versions.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const STAMP_PATTERN = /^<!-- uniweb-agents v([\d.]+) -->/
+
+/**
+ * Read the version stamp from an AGENTS.md file
+ * @param {string} filePath - Absolute path to AGENTS.md
+ * @returns {string|null} Version string or null if no stamp
+ */
+export function readAgentsVersion(filePath) {
+  if (!existsSync(filePath)) return null
+  try {
+    const firstLine = readFileSync(filePath, 'utf8').split('\n')[0]
+    const match = firstLine.match(STAMP_PATTERN)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Generate AGENTS.md content with version stamp
+ * @returns {string} Full AGENTS.md content with stamp
+ */
+export function generateAgentsContent() {
+  const partialsDir = join(__dirname, '..', '..', 'partials')
+  const agentsContent = readFileSync(join(partialsDir, 'agents.md'), 'utf8')
+  return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent}\n`
+}

package/src/utils/scaffold.js

@@ -11,7 +11,7 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import yaml from 'js-yaml'
 import { copyTemplateDirectory, registerVersions } from '../templates/processor.js'
-import { getVersionsForTemplates } from '../versions.js'
+import { getVersionsForTemplates, getCliVersion } from '../versions.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates')
@@ -36,6 +36,9 @@ export async function scaffoldWorkspace(targetDir, context, options = {}) {
   // because an empty packages: [] makes pnpm search parent directories.
   const skip = context.workspaceGlobs?.length ? [] : ['pnpm-workspace.yaml']
 
+  // Inject CLI version for AGENTS.md stamp
+  context = { ...context, cliVersion: getCliVersion() }
+
   const templatePath = join(TEMPLATES_DIR, 'workspace')
   await copyTemplateDirectory(templatePath, targetDir, context, {
     onProgress: options.onProgress,

package/src/versions.js

@@ -22,6 +22,15 @@ function getCliPackageJson() {
   return JSON.parse(readFileSync(packagePath, 'utf8'))
 }
 
+/**
+ * Get the CLI's own version
+ *
+ * @returns {string} CLI version (e.g., "0.8.32")
+ */
+export function getCliVersion() {
+  return getCliPackageJson().version
+}
+
 /**
  * Extract version number from version spec (e.g., "^0.1.4" -> "0.1.4")
  */

package/templates/workspace/AGENTS.md.hbs

@@ -1 +1,2 @@
+<!-- uniweb-agents v{{cliVersion}} -->
 {{> agents}}