create-kudzu 0.1.155 → 0.1.156

package/README.md

@@ -10,6 +10,77 @@ cd my-app
 npm run dev
 ```
 
-The generated project is a working showcase on `@kudzujs/core@^0.16.30` with reusable components, an interactive state example, a zero-JavaScript static route, page metadata, responsive source CSS, and `npm run check`. Configuration remains optional until the app needs custom assets, document defaults, navigation, or build hooks.
+The generated project is a working showcase on `@kudzujs/core@^0.16.34` with reusable components, an interactive state example, a zero-JavaScript static route, page metadata, responsive CSS, and `npm run check`. Configuration remains optional until the app needs custom assets, document defaults, navigation, or build hooks.
 
 Use `--no-install` to create the files without installing dependencies.
+
+## Optional AI authoring guidance
+
+`create-kudzu@0.1.156` adds optional local AI developer tools:
+
+```bash
+npm create kudzu@latest my-app -- --ai
+```
+
+From a source checkout:
+
+```bash
+node /path/to/kudzu/packages/create-kudzu/index.mjs my-app --ai
+```
+
+This adds a short `AGENTS.md`, a standard-library-only `kudzu-ai.mjs` developer
+tool, and an `ai` npm script. Check logs are ignored through `.kudzu-ai/`.
+Combine with `--no-install` to generate files without installing packages.
+Without `--ai`, the starter stays unchanged.
+
+### Developer tools
+
+```bash
+npm run ai -- docs
+npm run ai -- docs Authoring
+npm run ai -- check
+npm run ai -- check --timeout-ms 600000
+```
+
+- `docs` lists level-two headings from the installed core README, including the
+  installed version and file path. Supply one exact, case-insensitive heading
+  (quote multi-word headings) to return that section. Sections are capped at
+  6,000 characters with explicit truncation and original line ranges. Follow the
+  file reference if more is needed. This uses the generated npm dependency layout;
+  install dependencies before reading docs. It makes no network or model calls.
+- `check` executes the app's existing `npm run check`, including its npm lifecycle
+  hooks, from the project root. It returns JSON status, exit code, timing and a
+  log excerpt. Failure stays nonzero. The default timeout is five minutes; choose
+  an integer from 1 to 1,200,000 ms. Timeout/cancellation terminates the spawned
+  process group on Unix or process tree on Windows and reports failure.
+- Full stdout/stderr are retained in a unique `.kudzu-ai/check-*/output.log`.
+  Large logs show the first/last 2,048 bytes with an omission marker; an error may
+  be in the omitted middle. Read the full log when needed. Old logs are not deleted
+  automatically; remove `.kudzu-ai/` when no longer needed.
+- The tool does not cache checks or certify browser behavior. Later edits require
+  a new check. Scripts that intentionally detach background jobs or custom
+  deployment rules need their own lifecycle/asset handling. Use
+  `npm run --silent ai -- check` to suppress npm's outer lifecycle banner.
+
+Start a new [OpenCode](https://opencode.ai/docs/rules/) or
+[Codex](https://developers.openai.com/codex/agent-configuration/agents-md) session
+from the app root to use their documented project-instruction discovery. Other
+agents need support for `AGENTS.md` or an explicit request to read it. Editor
+installation alone does not load instructions. Overrides, disabled discovery,
+context limits, and headless modes can change loading; verify the effective
+instructions in the agent you actually use.
+
+AGENTS.md supplies guidance; kudzu-ai.mjs performs real document lookup and check
+execution. The host's existing shell tool can invoke it without an MCP connection
+or plugin. It does not intercept every agent action or force use of these commands.
+There is no additional dependency, agent installation, or model call for these
+tools. Both files stay outside `src` and `public` and are excluded by the default
+Kudzu build. Custom asset-copy/deployment settings can still publish root files.
+Instructions and tool responses add input context; lower total AI cost is unmeasured.
+
+For an existing app, generate a disposable `--ai --no-install` project, copy
+`kudzu-ai.mjs`, add `"ai": "node kudzu-ai.mjs"` to your scripts and `.kudzu-ai/` to
+your ignore rules, and merge the applicable instructions into your existing rules.
+Keep your real `check` script; do not make it invoke `ai check` recursively.
+The generator rejects nonempty targets. Generated tools/rules are snapshots, not
+auto-updated when Kudzu is upgraded; review them with your existing app setup.

package/ai.mjs

@@ -0,0 +1,112 @@
+import { spawn, spawnSync } from "node:child_process"
+import { mkdir, mkdtemp, open, readFile, realpath } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parseArgs } from "node:util"
+
+export async function docs(root, heading) {
+  const directory = join(root, "node_modules/@kudzujs/core")
+  const { version } = JSON.parse(await readFile(join(directory, "package.json"), "utf8"))
+  const path = join(directory, "README.md")
+  const lines = (await readFile(path, "utf8")).split(/\r?\n/)
+  const sections = []
+  let fence
+  for (const [index, line] of lines.entries()) {
+    const delimiter = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/)
+    if (delimiter) {
+      if (!fence) fence = delimiter[1]
+      else if (delimiter[1][0] === fence[0] && delimiter[1].length >= fence.length && !delimiter[2].trim()) fence = undefined
+      continue
+    }
+    const title = !fence && line.match(/^##[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/)
+    if (title) sections.push({ heading: title[1], start: index })
+  }
+  const result = { version, path, headings: sections.map(section => section.heading) }
+  if (heading === undefined) return result
+  const matches = sections.filter(section => section.heading.toLowerCase() === heading.toLowerCase())
+  if (matches.length !== 1) throw new Error(`Expected one exact README heading. Available: ${result.headings.join(", ")}`)
+  const section = matches[0], end = sections[sections.indexOf(section) + 1]?.start ?? lines.length
+  const text = lines.slice(section.start, end).join("\n")
+  return { version, path, heading: section.heading, startLine: section.start + 1, endLine: end, text: text.slice(0, 6000), truncated: text.length > 6000 }
+}
+
+export async function check(root, timeoutMs = 300000) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1200000) throw new Error("timeout-ms must be an integer from 1 to 1200000")
+  root = await realpath(root)
+  if (process.env.KUDZU_AI_CHECK_ROOT === root) throw new Error("scripts.check must not invoke ai check recursively")
+  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"))
+  if (typeof manifest.scripts?.check !== "string" || !manifest.scripts.check.trim()) throw new Error("package.json must define scripts.check")
+  const logs = join(root, ".kudzu-ai")
+  await mkdir(logs, { recursive: true })
+  const directory = await mkdtemp(join(logs, "check-")), path = join(directory, "output.log")
+  const log = await open(path, "wx+")
+  const start = performance.now()
+  try {
+    const result = await new Promise(resolveRun => {
+      const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "check"], {
+        cwd: root, detached: process.platform !== "win32", shell: process.platform === "win32",
+        stdio: ["ignore", log.fd, log.fd], env: { ...process.env, FORCE_COLOR: "0", KUDZU_AI_CHECK_ROOT: root },
+      })
+      let timedOut = false, interrupted = null, error = null
+      const terminate = () => {
+        if (!child.pid) return
+        if (process.platform === "win32") {
+          const killed = spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { encoding: "utf8" })
+          if (killed.status !== 0) error = killed.error?.message ?? killed.stderr ?? "Could not terminate check tree"
+        } else {
+          try { process.kill(-child.pid, "SIGKILL") } catch (failure) { if (failure.code !== "ESRCH") error = failure.message }
+        }
+      }
+      const onInterrupt = signal => { interrupted = signal; terminate() }
+      const onSigint = () => onInterrupt("SIGINT"), onSigterm = () => onInterrupt("SIGTERM")
+      process.once("SIGINT", onSigint)
+      process.once("SIGTERM", onSigterm)
+      const timer = setTimeout(() => { timedOut = true; terminate() }, timeoutMs)
+      child.once("error", failure => { error = failure.message })
+      child.once("close", (exitCode, signal) => {
+        clearTimeout(timer)
+        process.removeListener("SIGINT", onSigint)
+        process.removeListener("SIGTERM", onSigterm)
+        resolveRun({ exitCode, signal, timedOut, interrupted, error })
+      })
+    })
+    const { size } = await log.stat()
+    const buffer = Buffer.alloc(Math.min(size, 4096))
+    // ponytail: bounded head/tail is an excerpt, never a substitute for the retained full log.
+    let excerpt
+    if (size <= 4096) {
+      const { bytesRead } = await log.read(buffer, 0, buffer.length, 0)
+      excerpt = buffer.subarray(0, bytesRead).toString("utf8")
+    } else {
+      await log.read(buffer, 0, 2048, 0)
+      await log.read(buffer, 2048, 2048, size - 2048)
+      excerpt = buffer.subarray(0, 2048).toString("utf8") + "\n[... omitted; read full output.log ...]\n" + buffer.subarray(2048).toString("utf8")
+    }
+    return {
+      command: "npm run check", passed: result.exitCode === 0 && !result.timedOut && !result.interrupted && !result.error,
+      ...result, elapsedMs: Math.round(performance.now() - start),
+      log: { path, bytes: size, excerpt, truncated: size > 4096 },
+      browserVerified: false, note: "Fresh check result only; later edits invalidate it. Compiler success is not browser or accessibility proof.",
+    }
+  } finally {
+    await log.close()
+  }
+}
+
+if (process.argv[1] && await realpath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const { positionals, values } = parseArgs({ allowPositionals: true, strict: true, options: { "timeout-ms": { type: "string" } } })
+    const root = dirname(fileURLToPath(import.meta.url)), [command, heading] = positionals
+    let result
+    if (command === "docs" && positionals.length <= 2 && values["timeout-ms"] === undefined) result = await docs(root, heading)
+    else if (command === "check" && positionals.length === 1) {
+      if (values["timeout-ms"] !== undefined && !/^\d+$/.test(values["timeout-ms"])) throw new Error("timeout-ms must be a decimal integer")
+      result = await check(root, values["timeout-ms"] === undefined ? undefined : Number(values["timeout-ms"]))
+      if (!result.passed) process.exitCode = result.exitCode || 1
+    } else throw new Error("Use: npm run ai -- docs [heading] | npm run ai -- check [--timeout-ms 300000]")
+    process.stdout.write(JSON.stringify(result) + "\n")
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ error: error.message }) + "\n")
+    process.exitCode = 1
+  }
+}

package/index.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process"
-import { mkdir, readdir, writeFile } from "node:fs/promises"
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, resolve } from "node:path"
 
 const args = process.argv.slice(2)
 const skipInstall = args.includes("--no-install")
+const ai = args.includes("--ai")
 const target = args.find(argument => !argument.startsWith("-")) ?? "kudzu-app"
 const root = resolve(target)
 
@@ -33,7 +34,7 @@ const files = {
       check: "tsc --noEmit && kudzu build"
     },
     dependencies: {
-      "@kudzujs/core": "^0.16.30"
+      "@kudzujs/core": "^0.16.34"
     },
     devDependencies: {
       typescript: "^5.9.2"
@@ -233,6 +234,31 @@ Documentation: https://kudzujs.cloud/docs
 `
 }
 
+if (ai) {
+  files["kudzu-ai.mjs"] = await readFile(new URL("./ai.mjs", import.meta.url), "utf8")
+  const manifest = JSON.parse(files["package.json"])
+  manifest.scripts.ai = "node kudzu-ai.mjs"
+  files["package.json"] = `${JSON.stringify(manifest, null, 2)}\n`
+  files[".gitignore"] += ".kudzu-ai/\n"
+  files["AGENTS.md"] = `# Kudzu application
+
+## Write
+- This is a Kudzu app, not the compiler repository. Routes are in src/pages; index.tsx maps to /. Reuse the existing components, data, and CSS relevant to the task.
+- Use ordinary function components and declarative TSX. Import hooks from @kudzujs/core. React-shaped syntax is compiler input, not full React runtime compatibility; do not add React, hydration, or a client router as a workaround.
+- Prefer native HTML controls, anchors, and events. Read input values through event.currentTarget.value inside the handler. State setters update logical state immediately; DOM writes are batched.
+
+## Find answers when needed
+- npm run ai -- docs lists installed-version README headings. npm run ai -- docs Authoring reads one section. Full local guide: node_modules/@kudzujs/core/README.md; public types: node_modules/@kudzujs/core/framework/core.d.ts. Read what the task needs.
+- Full guide and current limits: https://kudzujs.cloud/docs. Online docs can differ from the installed version; use local build diagnostics to confirm support.
+
+## Verify
+- npm run ai -- check runs npm run check (typecheck + build) with a timeout, JSON status, bounded excerpt, and full log in .kudzu-ai. Read that log if the excerpt is insufficient. This already performs the check; subsequent edits require a fresh check. npm run dev starts the dev server. Fix source, not generated output.
+- Build success does not prove browser behavior or accessibility. Exercise affected interactions in a browser and check labels, keyboard use, and visible results. Report unavailable checks instead of claiming a pass.
+- Static routes must remain JavaScript-free. Raw HTML text scans and compiler reports are not proof of visible DOM or complete script exclusion. Preserve required checks; avoid repeatedly dumping minified assets.
+`
+  files["README.md"] += "\nAI authoring guidance: [AGENTS.md](AGENTS.md). Start a supporting coding agent from this project root.\n\nRun `npm run ai -- docs` to list installed README headings, `npm run ai -- docs Authoring` to read a section, and `npm run ai -- check` to typecheck/build with a bounded result. Full check logs stay in `.kudzu-ai/`; remove that directory when no longer needed. Check results do not verify browser behavior.\n"
+}
+
 await Promise.all(Object.entries(files).map(async ([file, content]) => {
   await writeFile(resolve(root, file), content)
 }))
@@ -243,3 +269,4 @@ if (!skipInstall) {
 }
 
 console.log(`\nCreated ${name} in ${root}${skipInstall ? "" : " with dependencies installed"}\n\n  cd ${target}\n${skipInstall ? "  npm install\n" : ""}  npm run dev\n`)
+if (ai) console.log("AI authoring guidance: AGENTS.md. Start OpenCode or Codex from the project root in a new session.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kudzu",
-  "version": "0.1.155",
+  "version": "0.1.156",
   "description": "Create a Kudzu project",
   "type": "module",
   "license": "MIT",
@@ -18,11 +18,12 @@
   },
   "files": [
     "index.mjs",
+    "ai.mjs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test ../../test/create-kudzu.test.mjs",
+    "test": "node --test ../../test/create-kudzu.test.mjs ../../test/create-kudzu-ai.test.mjs",
     "prepublishOnly": "npm test"
   },
   "keywords": [