Feat/publish readiness preflight (#26)

* feat(publish): add Webflow readiness preflight

* feat(publish): support explicit Webflow targets

* feat(docs): auto-create missing docs pages in Webflow

* feat(pages): add page management and typed page generation

* feat(scaffold): add typed Webflow selector contracts

* feat(pages): add page inspect and delete commands

* feat(tui): add interactive page management

* chore: release v1.3.4

Author: YNDmitry

README.md

@@ -115,6 +115,7 @@ How it works:
 - `src/features/*` is for reusable behaviors that can be mounted from global or page entries
 - `src/global/modules/*` contains reusable global behaviors that you choose to import from the global entry
 - `src/pages/*/index.ts` is for per-page code
+- `src/generated/wfkit-pages.ts` contains generated page slug types for `definePage(...)`
 - `src/utils/dom.ts` contains low-level DOM helpers
 - `src/utils/webflow.ts` contains DRY mount helpers that align page and feature bootstrapping with the Webflow runtime
 - `docs/index.md` is the default markdown entry for the docs hub page
@@ -137,6 +138,7 @@ wfkit docs
 ```
 
 By default this targets the Webflow page with slug `docs`.
+If that page does not exist yet, `wfkit docs` now creates it automatically before syncing the managed docs block.
 
 The command injects a managed docs block into that page's custom code and mounts the rendered content into:
 
@@ -169,6 +171,12 @@ Then:
 bun run dev
 ```
 
+When Webflow pages are added or renamed, refresh typed page names in the scaffold with:
+
+```bash
+bun run pages:types
+```
+
 This starts:
 
 - Vite on `http://localhost:5173`
@@ -408,6 +416,18 @@ Options:
 - `--publish` Publish the site after updating the docs page
 - `--notify` Show a desktop notification and play a sound when finished
 
+### `wfkit pages`
+
+Inspect and manage Webflow pages without opening the Designer.
+
+Subcommands:
+
+- `wfkit pages list` List static Webflow pages
+- `wfkit pages create --name "Docs" --slug docs` Create a static Webflow page
+- `wfkit pages inspect --slug docs` Inspect one page and its managed custom code blocks
+- `wfkit pages delete --slug docs --yes` Delete one static Webflow page
+- `wfkit pages types` Generate `src/generated/wfkit-pages.ts` from the current Webflow pages
+
 ### `wfkit migrate`
 
 Migrate inline Webflow custom code into local source files.

cmd/wfkit/app_commands.go

@@ -5,6 +5,7 @@ import "github.com/urfave/cli/v2"
 func buildCommands() []*cli.Command {
 	return []*cli.Command{
 		buildInitCommand(),
+		buildPagesCommand(),
 		buildDocsCommand(),
 		buildMigrateCommand(),
 		buildPublishCommand(),
@@ -16,6 +17,61 @@ func buildCommands() []*cli.Command {
 	}
 }
 
+func buildPagesCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "pages",
+		Usage: "Inspect, create, and type Webflow pages",
+		Subcommands: []*cli.Command{
+			{
+				Name:   "list",
+				Usage:  "List static Webflow pages for the current site",
+				Flags:  []cli.Flag{&cli.BoolFlag{Name: "json", Usage: "Print pages as JSON"}},
+				Action: pagesListMode,
+			},
+			{
+				Name:  "create",
+				Usage: "Create a new static Webflow page",
+				Flags: []cli.Flag{
+					&cli.StringFlag{Name: "name", Usage: "Page title to create"},
+					&cli.StringFlag{Name: "slug", Usage: "Page slug (defaults to a slugified title)"},
+					&cli.BoolFlag{Name: "json", Usage: "Print the created page as JSON"},
+					&cli.BoolFlag{Name: "types", Value: true, Usage: "Regenerate local page types after creating the page"},
+					&cli.StringFlag{Name: "output", Value: "src/generated/wfkit-pages.ts", Usage: "Output path for generated page types when --types is enabled"},
+				},
+				Action: pagesCreateMode,
+			},
+			{
+				Name:  "types",
+				Usage: "Generate typed page names from the current Webflow site",
+				Flags: []cli.Flag{
+					&cli.StringFlag{Name: "output", Value: "src/generated/wfkit-pages.ts", Usage: "Output path for generated page types"},
+				},
+				Action: pagesTypesMode,
+			},
+			{
+				Name:  "inspect",
+				Usage: "Inspect one Webflow page by slug or page id",
+				Flags: []cli.Flag{
+					&cli.StringFlag{Name: "slug", Usage: "Page slug to inspect"},
+					&cli.StringFlag{Name: "id", Usage: "Page id to inspect"},
+					&cli.BoolFlag{Name: "json", Usage: "Print the page as JSON"},
+				},
+				Action: pagesInspectMode,
+			},
+			{
+				Name:  "delete",
+				Usage: "Delete one Webflow page by slug or page id",
+				Flags: []cli.Flag{
+					&cli.StringFlag{Name: "slug", Usage: "Page slug to delete"},
+					&cli.StringFlag{Name: "id", Usage: "Page id to delete"},
+					&cli.BoolFlag{Name: "yes", Usage: "Delete without an extra safety prompt"},
+				},
+				Action: pagesDeleteMode,
+			},
+		},
+	}
+}
+
 func buildInitCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "init",
@@ -61,6 +117,7 @@ func buildMigrateCommand() *cli.Command {
 			&cli.BoolFlag{Name: "publish", Usage: "After writing local files, build assets, push the artifact branch, and update Webflow"},
 			&cli.StringFlag{Name: "custom-commit", Value: "Migrate Webflow page code via wfkit", Usage: "Custom commit message"},
 			&cli.StringFlag{Name: "delivery", Value: "cdn", Usage: "Delivery mode for --publish: cdn or inline"},
+			&cli.StringFlag{Name: "target", Value: "staging", Usage: "Webflow publish targets for --publish: staging, production, or all"},
 			&cli.StringFlag{Name: "asset-branch", Value: "wfkit-dist", Usage: "Git branch used for published build artifacts and jsDelivr URLs"},
 			&cli.StringFlag{Name: "branch", Hidden: true, Usage: "Deprecated alias for --asset-branch"},
 			&cli.StringFlag{Name: "build-dir", Value: "dist/assets", Usage: "Build directory"},
@@ -83,6 +140,7 @@ func buildPublishCommand() *cli.Command {
 			&cli.StringFlag{Name: "dev-host", Value: "localhost", Usage: "Local dev server host (dev mode)"},
 			&cli.StringFlag{Name: "custom-commit", Value: "Auto publish from wfkit tool", Usage: "Custom commit message"},
 			&cli.StringFlag{Name: "delivery", Value: "cdn", Usage: "Production delivery mode: cdn or inline"},
+			&cli.StringFlag{Name: "target", Value: "staging", Usage: "Webflow publish targets: staging, production, or all"},
 			&cli.StringFlag{Name: "asset-branch", Value: "wfkit-dist", Usage: "Git branch used for published build artifacts and jsDelivr URLs"},
 			&cli.StringFlag{Name: "branch", Hidden: true, Usage: "Deprecated alias for --asset-branch"},
 			&cli.StringFlag{Name: "build-dir", Value: "dist/assets", Usage: "Build directory"},

cmd/wfkit/docs_flow.go

@@ -157,6 +157,7 @@ func (f *docsFlow) printSuccess() {
 		"Markdown documentation has been published to the Webflow docs page.",
 		[]utils.SummaryMetric{
 			{Label: "Page", Value: f.options.PageSlug, Tone: "success"},
+			{Label: "Created", Value: map[bool]string{true: "yes", false: "no"}[f.result.Created], Tone: "info"},
 			{Label: "Published", Value: map[bool]string{true: "yes", false: "no"}[f.result.Published], Tone: "info"},
 		},
 		"git status",

cmd/wfkit/docs_report.go

@@ -11,8 +11,8 @@ func printDocsTimeline(authed, planned, applied bool) {
 	utils.PrintTimeline(
 		"Docs Timeline",
 		utils.TimelineStep{Label: "Authenticate", Status: timelineStatus(authed, false), Details: timelineDetails(authed, "Webflow session ready")},
-		utils.TimelineStep{Label: "Plan docs hub", Status: timelineStatus(planned, false), Details: timelineDetails(planned, "markdown rendered and target page resolved")},
-		utils.TimelineStep{Label: "Apply docs hub", Status: timelineStatus(applied, false), Details: timelineDetails(applied, "managed docs block updated")},
+		utils.TimelineStep{Label: "Plan docs hub", Status: timelineStatus(planned, false), Details: timelineDetails(planned, "markdown rendered and target page prepared")},
+		utils.TimelineStep{Label: "Apply docs hub", Status: timelineStatus(applied, false), Details: timelineDetails(applied, "page created or docs block updated")},
 	)
 }
 
@@ -29,6 +29,7 @@ func printDocsPlan(plan publish.DocsHubPlan) {
 func printDocsResult(result publish.DocsHubResult) {
 	utils.PrintSection("Docs Result")
 	utils.PrintSummary(
+		utils.SummaryMetric{Label: "Created", Value: map[bool]string{true: "yes", false: "no"}[result.Created], Tone: "info"},
 		utils.SummaryMetric{Label: "Updated", Value: map[bool]string{true: "yes", false: "no"}[result.Updated], Tone: "success"},
 		utils.SummaryMetric{Label: "Published", Value: map[bool]string{true: "yes", false: "no"}[result.Published], Tone: "info"},
 	)
@@ -37,6 +38,8 @@ func printDocsResult(result publish.DocsHubResult) {
 
 func docsStatus(action string) string {
 	switch action {
+	case "create":
+		return "CREATE"
 	case "update":
 		return "UPDATE"
 	case "up_to_date":

cmd/wfkit/doctor.go

@@ -82,12 +82,14 @@ func doctorDashboardCards(checks []doctorCheck) []utils.DashboardCard {
 		{key: "project", title: "Project"},
 		{key: "tooling", title: "Tooling"},
 		{key: "runtime", title: "Runtime"},
+		{key: "publish", title: "Publish"},
 	}
 
 	stats := map[string]*aggregate{
 		"project": {},
 		"tooling": {},
 		"runtime": {},
+		"publish": {},
 	}
 
 	for _, check := range checks {

cmd/wfkit/doctor_flow.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"wfkit/internal/config"
+	"wfkit/internal/webflow"
 )
 
 type doctorFlow struct {
@@ -66,10 +67,40 @@ func (f *doctorFlow) collectChecks() {
 			Status:   doctorWarn,
 			Message:  "skipped by flag",
 		})
+		f.checks = append(f.checks, doctorCheck{
+			Category: "publish",
+			Name:     "Publish readiness",
+			Status:   doctorWarn,
+			Message:  "skipped because auth checks are disabled",
+		})
+		return
+	}
+
+	authCheck, token, cookies := f.checkWebflowSession()
+	f.checks = append(f.checks, authCheck)
+
+	if authCheck.Status != doctorPass {
+		f.checks = append(f.checks, doctorCheck{
+			Category: "publish",
+			Name:     "Publish readiness",
+			Status:   doctorWarn,
+			Message:  "skipped because Webflow authentication is not ready",
+		})
+		return
+	}
+
+	preflight, err := webflow.GetPublishPreflight(f.context, f.config.AppName, token, cookies)
+	if err != nil {
+		f.checks = append(f.checks, doctorCheck{
+			Category: "publish",
+			Name:     "Publish readiness",
+			Status:   doctorWarn,
+			Message:  err.Error(),
+		})
 		return
 	}
 
-	f.checks = append(f.checks, checkWebflowAuth(f.context, f.config))
+	f.checks = append(f.checks, doctorChecksFromPublishPreflight(preflight)...)
 }
 
 func (f *doctorFlow) hasBlockingIssues() bool {
@@ -81,3 +112,22 @@ func (f *doctorFlow) hasBlockingIssues() bool {
 
 	return false
 }
+
+func (f *doctorFlow) checkWebflowSession() (doctorCheck, string, string) {
+	designURL := f.config.EffectiveDesignURL()
+	if designURL == "" {
+		return doctorCheck{Category: "runtime", Name: "Webflow auth", Status: doctorFail, Message: "cannot build design URL without appName"}, "", ""
+	}
+
+	token, cookies, err := webflow.GetCsrfTokenAndCookies(f.context, designURL)
+	if err != nil {
+		return doctorCheck{Category: "runtime", Name: "Webflow auth", Status: doctorWarn, Message: err.Error()}, "", ""
+	}
+
+	return doctorCheck{
+		Category: "runtime",
+		Name:     "Webflow auth",
+		Status:   doctorPass,
+		Message:  fmt.Sprintf("authenticated against %s", designURL),
+	}, token, cookies
+}

cmd/wfkit/interactive_flow.go

@@ -64,6 +64,8 @@ func (f *interactiveFlow) dispatch() error {
 		return initMode(f.cliContext)
 	case "docs":
 		return docsMode(f.cliContext)
+	case "pages":
+		return newInteractivePagesFlow(f.cliContext).run()
 	case "migrate":
 		return migrateMode(f.cliContext)
 	case "publish_prod":
@@ -115,6 +117,7 @@ func interactiveActionOptions() []huh.Option[string] {
 	return []huh.Option[string]{
 		huh.NewOption("Initialize a project", "init"),
 		huh.NewOption("Publish docs", "docs"),
+		huh.NewOption("Manage pages", "pages"),
 		huh.NewOption("Migrate page code", "migrate"),
 		huh.NewOption("Publish code to Webflow (prod)", "publish_prod"),
 		huh.NewOption("Start dev proxy", "proxy_dev"),