create-clientkit 1.0.0 → 1.0.2

package/README.md

@@ -1,24 +1,37 @@
 # create-clientkit
 
+[![npm](https://img.shields.io/npm/v/create-clientkit)](https://www.npmjs.com/package/create-clientkit)
+[![CI](https://github.com/JosuK22/create-clientkit/actions/workflows/ci.yml/badge.svg)](https://github.com/JosuK22/create-clientkit/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/create-clientkit)](https://nodejs.org)
+[![licence](https://img.shields.io/npm/l/create-clientkit)](./LICENSE)
+
 **Create the boring foundation of your next client website in seconds.**
 
+```sh
+npm create clientkit@latest acme-website
+```
+
 A scaffolding CLI for developers who build client websites over and over:
 freelancers, agencies and frontend teams. It generates the foundation you
-rebuild every time — layout, Coming Soon page, 404, SEO, robots, sitemap,
-structured data, favicon, accessibility baseline, build config — and then gets
-out of the way.
+rebuild every time — layout, a Coming Soon page, a custom 404, SEO metadata,
+`robots.txt`, a sitemap, structured data, a favicon, an accessibility baseline
+and build config — and then gets out of the way.
 
 It is **not** a website builder. You own the generated source from the moment
 it lands on disk.
 
-```sh
-npm create clientkit@latest acme-website
-```
-
----
+**What it generates** — a static [Astro](https://astro.build) 7 +
+[Tailwind CSS](https://tailwindcss.com) 4 site in TypeScript: responsive, light
+and dark themes, and no client-side JavaScript by default. Start in
+**Coming Soon** mode for a launch page, **Full** for a small multi-section home
+page, or **URL-less** when the domain is not decided yet.
 
-> **Status: pre-release (0.1.0).** Feature-complete for V1 and verified in CI
-> across Windows, macOS and Linux, but not yet published to npm.
+**What it is** — one bundled CLI with **zero runtime dependencies**, MIT
+licensed, published from CI with
+[provenance](https://docs.npmjs.com/generating-provenance-statements) and
+tested on Linux, Windows and macOS across Node 20.19, 22 and 24. The site it
+generates has its own dependencies — Astro and Tailwind, pinned exactly — which
+is a separate thing from the CLI's own dependency count.
 
 ---
 
@@ -41,19 +54,33 @@ and warns before generating that the project itself will need 22.12+.
 | Windows | yes | yes            | Node 20.19, 22, 24 (site: 22)     |
 | macOS   | yes | yes            | Node 20.19, 22, 24 (site: 22)     |
 
-> **Verification status.** Windows is verified directly — the full test suite,
-> clean-room packaging and generated-project builds are run there. The Linux
-> and macOS rows describe what `.github/workflows/ci.yml` covers; that
-> workflow has not yet executed on GitHub-hosted runners, so treat those rows
-> as intended coverage rather than observed results until the first CI run.
+> **Verification status.** Every row above is observed, not intended: the CI
+> workflow runs on GitHub-hosted runners for all three platforms on each push.
+> One exception is called out honestly — Ctrl+C cancellation cannot be tested
+> on Windows, which has neither pty allocation nor POSIX signal delivery to a
+> child process, so `scripts/cancel-check.mjs` prints the manual procedure
+> there instead of asserting anything.
 
 ## Usage
 
+Recommended — nothing to install first, and `@latest` sidesteps npm's
+initializer cache:
+
 ```sh
 npm create clientkit@latest [directory] [options]
+```
+
+The same binary is reachable through `npx`, if that suits your workflow better.
+It does the same thing:
+
+```sh
 npx create-clientkit@latest [directory] [options]
 ```
 
+Note that this is about how you _invoke_ the CLI. Which package manager installs
+the generated project's dependencies is a separate choice — detected from your
+environment, or forced with `--pm`.
+
 | Flag                  | Description                               |
 | --------------------- | ----------------------------------------- |
 | `-t, --template <id>` | Template to scaffold from                 |
@@ -116,11 +143,27 @@ One template ships in V1:
 | ---------------- | --------------------------------------- | --------------------- |
 | `astro-tailwind` | Astro 7, Tailwind CSS 4, TypeScript 5.9 | `coming-soon`, `full` |
 
-- **`coming-soon`** — a single polished launch page you can put live today.
-- **`full`** — a small home page with sections, on the same design system.
+- **`coming-soon`** — a single polished launch page you can put live today,
+  with an optional launch date and a progressive-enhancement countdown.
+- **`full`** — a small multi-section home page, on the same design system.
 
 Both include the custom 404, the design system and the full SEO layer.
 
+### URL-less
+
+Not a third mode — a state either mode starts in, and a supported one. When you
+have not decided on a domain, leave the production URL unset and the generated
+site **omits** every absolute tag rather than pointing it at a guess: no
+canonical, no `og:url`, no sitemap, and no `Sitemap:` line in `robots.txt`.
+
+```sh
+npm create clientkit@latest acme-website --yes   # no --url: URL-less
+```
+
+Set `SITE.url` in `src/config/site.config.ts` whenever the domain is known and
+all of it appears on the next build. Nothing needs regenerating, and no
+placeholder domain was ever written to disk.
+
 ## The generated project
 
 ```sh
@@ -166,12 +209,18 @@ on after launch keeps the real site invisible.
 
 1. Set `SITE.url` in `src/config/site.config.ts` — canonical URLs and the
    sitemap depend on it.
-2. Replace `public/favicon.svg` with the client's mark.
-3. Add a 1200×630 image to `public/` and set `SEO.image` if you want social
-   previews. No `og:image` is emitted until you do.
-4. Fill in `CONTACT` and `SOCIAL` — anything left empty is not rendered, and
+2. Rewrite `SITE.description`. It is generated as `Official website of <Name>.`
+   — deliberately generic, because the CLI will not invent claims about a
+   business it knows nothing about. It is a placeholder, and it becomes the
+   meta description, `og:description` and the X card description. Aim for
+   roughly 120–160 characters of real copy.
+3. Replace `public/favicon.svg` with the client's mark.
+4. Add a 1200×630 image to `public/` and set `SEO.image` if you want social
+   previews. No `og:image` is emitted until you do, and the X card stays
+   `summary` rather than rendering an empty `summary_large_image`.
+5. Fill in `CONTACT` and `SOCIAL` — anything left empty is not rendered, and
    not claimed in the structured data.
-5. `npm run check && npm run build`, then deploy `dist/` as a static site.
+6. `npm run check && npm run build`, then deploy `dist/` as a static site.
 
 Only the origin of `SITE.url` is used. To deploy under a subpath, also set
 `base` in `astro.config.mjs`.
@@ -222,6 +271,13 @@ The CLI publishes with `dependencies: {}` — its dependencies are bundled into
 resolution. See [THIRD-PARTY.md](./THIRD-PARTY.md) and
 [RELEASING.md](./RELEASING.md).
 
+## Contributing
+
+Bug reports and ideas are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+The quickest useful report is an
+[issue from a template](https://github.com/JosuK22/create-clientkit/issues/new/choose),
+since they ask for the versions and the exact command up front.
+
 ## Licence
 
 MIT — see [LICENSE](./LICENSE). Generated client projects are **not** MIT; they

package/dist/cli.js

@@ -2418,9 +2418,12 @@ function helpText() {
     npm create clientkit@latest acme-website --yes --no-install
     npm create clientkit@latest --from ./agency-preset.json --dry-run
 
-  Note
-    Early build: configuration is resolved and validated, but no files are
-    generated yet.
+  Notes
+    Dependencies are installed and a git repository is initialised by default.
+    Pass --no-install or --no-git to skip either.
+
+    The generated project is yours - private, unlicensed and dependency-pinned.
+    Nothing phones home and nothing is downloaded beyond your own install.
 `.trimStart();
 }
 
@@ -2474,7 +2477,7 @@ var Logger = class {
 };
 
 // src/version.ts
-var CLI_VERSION = true ? "1.0.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "1.0.2" : "0.0.0-dev";
 
 // src/cli.ts
 async function main(argv, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-clientkit",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Create the boring foundation of your next client website in seconds.",
   "keywords": [
     "cli",
@@ -51,10 +51,11 @@
     "audit": "node scripts/audit-site.mjs",
     "preflight": "node scripts/preflight.mjs",
     "verify": "npm run typecheck && npm run lint && npm run format:check && npm run test && npm run build",
-    "prepublishOnly": "npm run preflight",
+    "prepublishOnly": "node scripts/preflight.mjs --skip-if-verified",
     "cancel-check": "node scripts/cancel-check.mjs",
     "drift": "node scripts/drift-probe.mjs",
-    "drift:report": "node scripts/drift-probe.mjs --report"
+    "drift:report": "node scripts/drift-probe.mjs --report",
+    "drift:selftest": "node scripts/drift-probe.mjs --simulate-drift tailwindcss@4.3.2"
   },
   "devDependencies": {
     "@clack/prompts": "^0.11.0",

package/templates/astro-tailwind/base/README.md

@@ -24,7 +24,8 @@ npm run dev
 1. **`src/config/site.config.ts`** - the single source of truth, and the only
    file you need for most client changes:
    - `SITE` - name, description, production URL, locale, author
-   - `NAV` - header links (empty means no menu is rendered at all)
+   - `NAV` - header links (empty means no menu is rendered at all; in
+     coming-soon mode the home page has no header, so they show on the 404 only)
    - `SOCIAL` - social profiles (empty means no links are rendered)
    - `CONTACT` - email, phone, location; each is optional
    - `LAUNCH` - optional launch date and countdown
@@ -78,6 +79,20 @@ sitemap and the sitemap line in `robots.txt` - rather than pointing them at a
 domain nobody owns yet. Fill `SITE.url` in and they all appear. Only the
 origin is used; a subpath deployment also needs Astro's `base` option.
 
+### Social previews and the description
+
+`SITE.description` arrives as `Official website of {{siteName}}.` That is a
+placeholder, not a suggestion. It was generated without knowing anything about
+the business, and it becomes the meta description, `og:description` and the X
+card description - so it is worth replacing with real copy, roughly 120-160
+characters, before launch.
+
+`SEO.image` starts empty and no `og:image` is emitted while it is. The X card
+stays `summary` in that state rather than claiming `summary_large_image` with
+no image to show, which renders as an empty card. Drop a 1200x630 image into
+`public/`, point `SEO.image` at it, and the card switches to the large format
+on its own.
+
 ### Indexing
 
 `SEO.noindex` controls it, and it is `false` by default so a launched site is

package/templates/astro-tailwind/base/src/config/site.config.ts

@@ -106,6 +106,12 @@ export const SITE: SiteIdentity = {
 /**
  * Site navigation. Empty by default: the header renders no menu at all rather
  * than inventing links. Add items once real pages or sections exist.
+ *
+ * NAV drives the header, so it shows up only on pages that render one. In
+ * coming-soon mode the home page deliberately has no header - it carries its
+ * own brand lockup instead - so there these links appear on the 404 page only.
+ * Delete `showHeader={false}` from src/pages/index.astro if you want a header
+ * and menu on the launch page too.
  */
 export const NAV: NavItem[] = [];
 

package/templates/astro-tailwind/modes/coming-soon/src/pages/index.astro

@@ -10,7 +10,17 @@ const hasSocial = SOCIAL.some((link) => link.label !== '' && link.href !== '');
 const hasLaunch = LAUNCH.enabled && LAUNCH.date !== '';
 ---
 
-{/* The page carries its own brand lockup, so a header would only repeat it. */}
+{
+  /*
+  No header here: the page carries its own brand lockup below, and repeating it
+  in a bar would say the same thing twice on one screen. A launch page also has
+  nowhere to navigate to yet.
+
+  This is why NAV in src/config/site.config.ts does not show on this page - it
+  drives the header, and there is no header. It still applies to the 404 page.
+  Delete showHeader={false} if you want a header and menu here too.
+*/
+}
 <BaseLayout showHeader={false} measure="narrow">
   <div class="hero">
     <div class="glow" aria-hidden="true"></div>