@codemeall/create-word-pages 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemeall/create-word-pages",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Scaffold a Word Pages Obsidian-to-GitHub-Pages starter.",
   "type": "module",
   "bin": {

package/template/wizard/src/configValidation.js

@@ -0,0 +1,32 @@
+const baseUrlPattern = /^[A-Za-z0-9.-]+(\/[A-Za-z0-9._~-]+)*$/
+
+export const requiredSiteFields = ["title", "githubUsername", "repositoryName", "baseUrl"]
+
+export function validateWordPagesConfig(config) {
+  const fieldErrors = {}
+  const site = config?.site ?? {}
+
+  for (const field of requiredSiteFields) {
+    if (!String(site[field] ?? "").trim()) {
+      fieldErrors[field] = "Required"
+    }
+  }
+
+  const baseUrl = String(site.baseUrl ?? "").trim()
+  if (baseUrl) {
+    if (/^[a-z][a-z\d+.-]*:\/\//i.test(baseUrl)) {
+      fieldErrors.baseUrl = "Use the Pages URL without https://"
+    } else if (/\s/.test(baseUrl)) {
+      fieldErrors.baseUrl = "Remove spaces from the Pages URL"
+    } else if (baseUrl.startsWith("/") || baseUrl.endsWith("/")) {
+      fieldErrors.baseUrl = "Do not use leading or trailing slashes"
+    } else if (!baseUrlPattern.test(baseUrl)) {
+      fieldErrors.baseUrl = "Use a value like octocat.github.io/my-site"
+    }
+  }
+
+  return {
+    ok: Object.keys(fieldErrors).length === 0,
+    fieldErrors
+  }
+}

package/template/wizard/src/main.tsx

@@ -1,7 +1,10 @@
 import React, { useEffect, useMemo, useState } from "react"
 import { createRoot } from "react-dom/client"
+import { validateWordPagesConfig } from "./configValidation.js"
 import "./styles.css"
 
+type SaveState = "idle" | "dirty" | "saving" | "saved" | "failed"
+
 type WordPagesConfig = {
   site: {
     title: string
@@ -21,6 +24,8 @@ type WordPagesConfig = {
   }
 }
 
+type SiteFieldErrors = Partial<Record<keyof WordPagesConfig["site"], string>>
+
 function deriveBaseUrl(username: string, repositoryName: string) {
   if (!username || !repositoryName) return ""
   if (repositoryName.toLowerCase() === `${username.toLowerCase()}.github.io`) return `${username}.github.io`
@@ -34,15 +39,26 @@ function displayPagesUrl(baseUrl: string) {
 function App() {
   const [config, setConfig] = useState<WordPagesConfig | null>(null)
   const [status, setStatus] = useState("Loading")
+  const [saveState, setSaveState] = useState<SaveState>("idle")
+  const [message, setMessage] = useState("Load the wizard, edit settings, then save.")
+  const [lastSavedAt, setLastSavedAt] = useState("")
 
   useEffect(() => {
     fetch("/api/config")
-      .then((response) => response.json())
+      .then((response) => {
+        if (!response.ok) throw new Error("Could not load word-pages.config.json")
+        return response.json()
+      })
       .then((data) => {
         setConfig(data)
         setStatus("Ready")
+        setMessage("Configuration loaded from word-pages.config.json.")
+      })
+      .catch((error) => {
+        setStatus("Could not load configuration")
+        setSaveState("failed")
+        setMessage(error instanceof Error ? error.message : "Restart npm run wizard from the site root.")
       })
-      .catch(() => setStatus("Could not load configuration"))
   }, [])
 
   const pageUrl = useMemo(() => {
@@ -50,8 +66,23 @@ function App() {
     return displayPagesUrl(deriveBaseUrl(config.site.githubUsername, config.site.repositoryName))
   }, [config])
 
+  const fieldErrors = useMemo<SiteFieldErrors>(() => {
+    if (!config) return {}
+    return validateWordPagesConfig(config).fieldErrors
+  }, [config])
+  const canSave = Object.keys(fieldErrors).length === 0 && saveState !== "saving"
+
   if (!config) {
-    return <main className="shell"><p>{status}</p></main>
+    return (
+      <main className="shell">
+        <section className={`status-panel ${saveState}`} role="status" aria-live="polite">
+          <div>
+            <strong>{status}</strong>
+            <p>{message}</p>
+          </div>
+        </section>
+      </main>
+    )
   }
 
   function updateSite<K extends keyof WordPagesConfig["site"]>(key: K, value: WordPagesConfig["site"][K]) {
@@ -68,16 +99,47 @@ function App() {
           : current.site.baseUrl
       }
     })
+    setSaveState("dirty")
+    setMessage("Unsaved changes. Click Save changes to write word-pages.config.json.")
   }
 
   async function save() {
-    setStatus("Saving")
-    const response = await fetch("/api/config", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(config)
-    })
-    setStatus(response.ok ? "Saved" : "Save failed")
+    const validation = validateWordPagesConfig(config)
+    if (!validation.ok) {
+      setStatus("Required fields missing")
+      setSaveState("failed")
+      setMessage("Complete the required fields before saving word-pages.config.json.")
+      return
+    }
+
+    try {
+      setStatus("Saving")
+      setSaveState("saving")
+      setMessage("Saving word-pages.config.json...")
+
+      const response = await fetch("/api/config", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(config)
+      })
+      const result = await response.json().catch(() => ({ message: "No response body" }))
+      if (!response.ok || result.ok === false) {
+        if (result.fieldErrors) {
+          throw new Error(result.message ?? "Complete the required fields before saving.")
+        }
+        throw new Error(result.message ?? "Save failed")
+      }
+
+      const savedAt = new Date().toLocaleTimeString()
+      setStatus("Saved")
+      setSaveState("saved")
+      setLastSavedAt(savedAt)
+      setMessage(`Saved to word-pages.config.json at ${savedAt}. Run npm run preview in another terminal to rebuild the site.`)
+    } catch (error) {
+      setStatus("Save failed")
+      setSaveState("failed")
+      setMessage(error instanceof Error ? error.message : "Save failed")
+    }
   }
 
   return (
@@ -88,13 +150,24 @@ function App() {
           <h1>Configure your Obsidian-powered site.</h1>
           <p className="lede">This wizard writes local configuration only. It does not ask for GitHub credentials and does not upload your vault.</p>
         </div>
-        <button onClick={save}>Save</button>
+        <button type="button" onClick={save} disabled={!canSave}>
+          {saveState === "saving" ? "Saving..." : "Save changes"}
+        </button>
+      </section>
+
+      <section className={`status-panel ${saveState}`} role="status" aria-live="polite">
+        <div>
+          <strong>{status}</strong>
+          <p>{message}</p>
+        </div>
+        {lastSavedAt && <span>Last saved {lastSavedAt}</span>}
       </section>
 
       <section className="grid">
         <label>
           Site title
-          <input value={config.site.title} onChange={(event) => updateSite("title", event.target.value)} />
+          <input value={config.site.title} onChange={(event) => updateSite("title", event.target.value)} aria-invalid={Boolean(fieldErrors.title)} />
+          {fieldErrors.title && <span className="field-error">{fieldErrors.title}</span>}
         </label>
         <label>
           Author or organization
@@ -106,11 +179,13 @@ function App() {
         </label>
         <label>
           GitHub username
-          <input value={config.site.githubUsername} onChange={(event) => updateSite("githubUsername", event.target.value)} />
+          <input value={config.site.githubUsername} onChange={(event) => updateSite("githubUsername", event.target.value)} aria-invalid={Boolean(fieldErrors.githubUsername)} />
+          {fieldErrors.githubUsername && <span className="field-error">{fieldErrors.githubUsername}</span>}
         </label>
         <label>
           Repository name
-          <input value={config.site.repositoryName} onChange={(event) => updateSite("repositoryName", event.target.value)} />
+          <input value={config.site.repositoryName} onChange={(event) => updateSite("repositoryName", event.target.value)} aria-invalid={Boolean(fieldErrors.repositoryName)} />
+          {fieldErrors.repositoryName && <span className="field-error">{fieldErrors.repositoryName}</span>}
         </label>
         <label>
           Repository visibility
@@ -122,7 +197,8 @@ function App() {
         </label>
         <label>
           GitHub Pages base URL
-          <input value={config.site.baseUrl} onChange={(event) => updateSite("baseUrl", event.target.value)} />
+          <input value={config.site.baseUrl} onChange={(event) => updateSite("baseUrl", event.target.value)} aria-invalid={Boolean(fieldErrors.baseUrl)} />
+          {fieldErrors.baseUrl && <span className="field-error">{fieldErrors.baseUrl}</span>}
         </label>
       </section>
 
@@ -133,6 +209,27 @@ function App() {
         <p><strong>Expected Pages URL:</strong> {pageUrl}</p>
       </section>
 
+      <section className="next-steps">
+        <h2>Next steps</h2>
+        <div className="steps-grid">
+          <div>
+            <span>1</span>
+            <h3>Edit content</h3>
+            <p>Open <code>content/</code> in Obsidian and update pages, posts, and notes.</p>
+          </div>
+          <div>
+            <span>2</span>
+            <h3>Preview locally</h3>
+            <p>Run <code>npm run preview</code> in a second terminal. Quartz serves the site at its local preview URL.</p>
+          </div>
+          <div>
+            <span>3</span>
+            <h3>Publish</h3>
+            <p>Commit, push to GitHub, and enable Pages with GitHub Actions.</p>
+          </div>
+        </div>
+      </section>
+
       <footer>
         <span>{status}</span>
         <span>Next: open <code>content/</code> in Obsidian, then run <code>npm run preview</code>.</span>

package/template/wizard/src/styles.css

@@ -59,6 +59,48 @@ button {
   cursor: pointer;
 }
 
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.72;
+}
+
+.status-panel {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  margin: 24px 0 0;
+  border: 1px solid #d8d0c0;
+  border-left: 5px solid #8a8376;
+  border-radius: 8px;
+  padding: 16px;
+  background: #fffdf8;
+}
+
+.status-panel p {
+  margin: 4px 0 0;
+  color: #5f594f;
+}
+
+.status-panel.saved {
+  border-left-color: #28786f;
+}
+
+.status-panel.dirty,
+.status-panel.saving {
+  border-left-color: #8d5c2c;
+}
+
+.status-panel.failed {
+  border-left-color: #b83232;
+}
+
+.status-panel > span {
+  white-space: nowrap;
+  color: #6f675c;
+  font-size: 0.92rem;
+}
+
 .grid {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -89,6 +131,17 @@ textarea {
   font: inherit;
 }
 
+input[aria-invalid="true"] {
+  border-color: #b83232;
+  outline-color: #b83232;
+}
+
+.field-error {
+  color: #9f2525;
+  font-size: 0.88rem;
+  font-weight: 700;
+}
+
 textarea {
   min-height: 104px;
   resize: vertical;
@@ -105,6 +158,44 @@ textarea {
   margin-top: 0;
 }
 
+.next-steps {
+  margin-top: 24px;
+}
+
+.steps-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.steps-grid > div {
+  border: 1px solid #ded8ca;
+  border-radius: 8px;
+  padding: 18px;
+  background: #fffdf8;
+}
+
+.steps-grid span {
+  display: inline-grid;
+  width: 28px;
+  height: 28px;
+  place-items: center;
+  border-radius: 50%;
+  color: white;
+  background: #28786f;
+  font-size: 0.9rem;
+  font-weight: 800;
+}
+
+.steps-grid h3 {
+  margin: 14px 0 8px;
+}
+
+.steps-grid p {
+  margin: 0;
+  color: #5f594f;
+}
+
 code {
   border-radius: 4px;
   padding: 2px 5px;
@@ -121,12 +212,18 @@ footer {
 
 @media (max-width: 720px) {
   .hero,
-  footer {
+  footer,
+  .status-panel {
     align-items: stretch;
     flex-direction: column;
   }
 
-  .grid {
+  .grid,
+  .steps-grid {
     grid-template-columns: 1fr;
   }
+
+  .status-panel > span {
+    white-space: normal;
+  }
 }

package/template/wizard/vite.config.ts

@@ -2,8 +2,23 @@ import { defineConfig } from "vite"
 import react from "@vitejs/plugin-react"
 import { readFile, writeFile } from "node:fs/promises"
 import path from "node:path"
+import { validateWordPagesConfig } from "./src/configValidation.js"
 
 const configPath = path.resolve(process.cwd(), "word-pages.config.json")
+let printedCompletionHandoff = false
+
+function printCompletionHandoff() {
+  if (printedCompletionHandoff) return
+  printedCompletionHandoff = true
+  console.log(`
+Word Pages setup saved.
+
+Next steps:
+1. Open content/ in Obsidian and edit your pages, posts, and notes.
+2. In another terminal, run: npm run preview
+3. When ready, commit, push to GitHub, and enable Pages with GitHub Actions.
+`)
+}
 
 export default defineConfig({
   root: "wizard",
@@ -13,29 +28,61 @@ export default defineConfig({
       name: "word-pages-config-api",
       configureServer(server) {
         server.middlewares.use("/api/config", async (req, res) => {
-          if (req.method === "GET") {
-            const body = await readFile(configPath, "utf8")
-            res.setHeader("Content-Type", "application/json")
-            res.end(body)
-            return
-          }
-
-          if (req.method === "POST") {
-            let raw = ""
-            req.on("data", (chunk) => {
-              raw += chunk
-            })
-            req.on("end", async () => {
-              const parsed = JSON.parse(raw)
-              await writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`)
+          try {
+            if (req.method === "GET") {
+              const body = await readFile(configPath, "utf8")
               res.setHeader("Content-Type", "application/json")
-              res.end(JSON.stringify({ ok: true }))
-            })
-            return
-          }
+              res.end(body)
+              return
+            }
 
-          res.statusCode = 405
-          res.end("Method not allowed")
+            if (req.method === "POST") {
+              let raw = ""
+              req.on("data", (chunk) => {
+                raw += chunk
+              })
+              req.on("end", async () => {
+                try {
+                  const parsed = JSON.parse(raw)
+                  const validation = validateWordPagesConfig(parsed)
+                  if (!validation.ok) {
+                    res.statusCode = 400
+                    res.setHeader("Content-Type", "application/json")
+                    res.end(JSON.stringify({
+                      ok: false,
+                      message: "Complete the required fields before saving.",
+                      fieldErrors: validation.fieldErrors
+                    }))
+                    return
+                  }
+
+                  await writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`)
+                  printCompletionHandoff()
+                  res.setHeader("Content-Type", "application/json")
+                  res.end(JSON.stringify({ ok: true, path: configPath }))
+                } catch (error) {
+                  res.statusCode = 500
+                  res.setHeader("Content-Type", "application/json")
+                  res.end(JSON.stringify({
+                    ok: false,
+                    message: error instanceof Error ? error.message : "Could not save configuration"
+                  }))
+                }
+              })
+              return
+            }
+
+            res.statusCode = 405
+            res.setHeader("Content-Type", "application/json")
+            res.end(JSON.stringify({ ok: false, message: "Method not allowed" }))
+          } catch (error) {
+            res.statusCode = 500
+            res.setHeader("Content-Type", "application/json")
+            res.end(JSON.stringify({
+              ok: false,
+              message: error instanceof Error ? error.message : "Configuration API failed"
+            }))
+          }
         })
       }
     }