@clubedge/create-clubedge-app 0.1.3 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.1.9
+
+- Use npm Trusted Publishing with GitHub Actions OIDC for releases.
+- Use an npm CLI version supported by Trusted Publishing and remove the token-based publish dependency.
+
+## 0.1.8
+
+- Correct the pinned Starter commit to the commit actually resolved by the immutable `v0.1.1` tag.
+
+## 0.1.7
+
+- Pin the default Starter reference to the tested `v0.1.1` release, including the corrected browser contract.
+
+## 0.1.6
+
+- Move the CLI and Starter repository references to the `Clubedge` GitHub organization.
+- Update package metadata, documentation, tests, and generated provenance for the organization repositories.
+
+## 0.1.5
+
+- Verify the default Starter tag resolves to its expected commit and record that commit in generated metadata.
+- Add a post-publish smoke-test workflow for the published npm package.
+
+## 0.1.4
+
+- Pin the default Starter reference to the tested release tag `v0.1.0`.
+- Record the CLI version and Starter reference in generated project metadata and documentation.
+- Add scheduled compatibility verification for the latest Starter `main` branch.
+- Document the CLI-to-Starter version relationship and release workflow.
+
 ## 0.1.3
 
 - Keep generated project-name customization aligned with the dashboard's route-local sidebar.

package/README.md

@@ -1,11 +1,38 @@
 # create-clubedge-app
 
-[![CI](https://github.com/yassine-ahmed/create-clubedge-app/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yassine-ahmed/create-clubedge-app/actions/workflows/ci.yml)
+[![CI](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 
-Create a Next.js application from the [Clubedge Starter](https://github.com/yassine-ahmed/clubedge-starter) reference implementation.
+Create a Next.js application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
 
-The CLI downloads the starter repository, names the generated project, creates `apps/web/.env.local` from the example, initializes Git, and installs dependencies. The starter remains the source of truth for the generated architecture.
+The CLI downloads a tested Starter release, names the generated project, creates `apps/web/.env.local` from the example, initializes Git, and installs dependencies. The Starter remains the source of truth for the generated architecture.
+
+## Version relationship
+
+Each CLI release is tested against one specific Starter release:
+
+```text
+create-clubedge-app v0.1.9
+        |
+        v
+Clubedge Starter v0.1.1
+commit 0be0c18d41f01cd011c576fb65c25711081b8ad4
+```
+
+The current relationship is:
+
+| CLI release | Default Starter release | Meaning |
+| --- | --- | --- |
+| `create-clubedge-app@0.1.9` | `clubedge-starter@v0.1.1` | The CLI's required, tested default |
+
+This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
+
+The `v0.1.1` tag is expected to resolve to commit
+`0be0c18d41f01cd011c576fb65c25711081b8ad4`. The CLI verifies this before
+scaffolding with the default reference and fails rather than silently using a
+moved tag.
+
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.2.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
@@ -46,7 +73,7 @@ pnpm dlx @clubedge/create-clubedge-app
 ```text
 Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
---ref <branch-or-tag>  Select a branch or tag from the starter repository (default: main)
+--ref <ref>            Select a starter tag, branch, or commit (default: v0.1.1)
 --no-install           Skip pnpm install
 --no-git               Skip Git initialization
 -h, --help             Show help
@@ -56,15 +83,31 @@ Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 Examples:
 
 ```sh
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v1.0.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref <starter-tag-or-commit>
 pnpm dlx @clubedge/create-clubedge-app my-app --no-install
 ```
 
-The target directory must be empty or not exist. The CLI will not delete or overwrite files in a non-empty target directory. The default `main` ref follows the current reference implementation; use a tag to scaffold a specific starter revision.
+The target directory must be empty or not exist. The CLI will not delete or overwrite files in a non-empty target directory. The default is the tested `v0.1.1` Starter release, so the same CLI version produces the same Starter revision. Use `--ref` to explicitly select a tag, branch, or commit.
+
+The default is the tested Starter release tag `v0.1.1`. Every generated project records its CLI version, Starter repository, exact Starter ref, and resolved Starter commit in `package.json` and `README.md`.
+
+Use `--ref` only when you intentionally want a different Starter revision:
+
+```sh
+# Reproduce the supported default
+pnpm dlx @clubedge/create-clubedge-app my-app
+
+# Try an unreleased Starter change
+pnpm dlx @clubedge/create-clubedge-app my-app --ref main
+
+# Reproduce a specific Starter release or commit
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.1.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
+```
 
 ## How it works
 
-This first CLI release scaffolds the complete reference starter. It does not yet offer selectable SaaS, dashboard, or minimal feature presets; those should be added once each preset has a distinct, maintained template. This keeps CLI output aligned with the reference repo instead of creating a second, drifting copy of its source.
+This CLI scaffolds the complete reference Starter. It does not yet offer selectable SaaS, dashboard, or minimal feature presets; those should be added once each preset has a distinct, maintained template. This keeps CLI output aligned with the Starter repository instead of creating a second, drifting copy of its source.
 
 ## Development
 
@@ -76,7 +119,26 @@ pnpm check
 pnpm test
 ```
 
-CI also scaffolds a clean project from the current starter, installs its dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts the generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon.
+CI scaffolds a clean project from the pinned Starter release, installs its dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts the generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon. A scheduled, non-blocking compatibility job also checks Starter `main`.
+
+## Release workflow
+
+### Starter maintainers
+
+1. Make and validate changes in `clubedge-starter`.
+2. Run lint, typecheck, unit tests, browser tests, and production build.
+3. Update the Starter package versions.
+4. Commit `main`, create a release tag such as `v0.2.0`, and publish the Starter release.
+
+### CLI maintainers
+
+1. Change `defaultStarterRef` in [`bin/create.mjs`](bin/create.mjs) to the new tested Starter tag.
+2. Update the version relationship table and changelog.
+3. Generate a clean project from that exact tag.
+4. Run install, lint, typecheck, unit tests, browser tests, production build, and runtime smoke checks.
+5. Publish a new CLI version only after the generated-project verification passes.
+
+The required CI job always tests the pinned default. The scheduled compatibility job tests Starter `main` early, but unreleased Starter changes must not change the stable CLI default.
 
 ## Contributing
 

package/bin/create.mjs

@@ -8,8 +8,9 @@ import { basename, dirname, join, resolve } from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
 
-const starterRepository = "yassine-ahmed/clubedge-starter";
-const defaultRef = "main";
+const starterRepository = "Clubedge/clubedge-starter";
+const defaultStarterRef = "v0.1.1";
+const defaultStarterCommit = "0be0c18d41f01cd011c576fb65c25711081b8ad4";
 const packageVersion = JSON.parse(
   await readFile(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
@@ -19,12 +20,14 @@ function showHelp() {
 create-clubedge-app ${packageVersion}
 
 Create a Next.js project from the Clubedge Starter reference repository.
+This CLI release uses Starter ${defaultStarterRef} by default.
+Expected Starter commit: ${defaultStarterCommit}
 
 Usage:
   pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
 Options:
-  --ref <branch-or-tag>  Starter branch or tag to scaffold (default: ${defaultRef})
+  --ref <ref>            Starter tag, branch, or commit to scaffold (default: ${defaultStarterRef})
   --no-install           Skip dependency installation
   --no-git               Skip Git repository initialization
   -h, --help             Show this help
@@ -32,13 +35,16 @@ Options:
 
 Examples:
   pnpm dlx @clubedge/create-clubedge-app my-app
-  pnpm dlx @clubedge/create-clubedge-app my-app --ref v1.0.0
+  pnpm dlx @clubedge/create-clubedge-app my-app --ref <starter-tag-or-commit>
   pnpm dlx @clubedge/create-clubedge-app my-app --no-install
+
+Release model:
+  CLI ${packageVersion} -> Starter ${defaultStarterRef}
 `);
 }
 
 function parseArguments(args) {
-  const options = { install: true, git: true, ref: defaultRef, projectDirectory: undefined };
+  const options = { install: true, git: true, ref: defaultStarterRef, projectDirectory: undefined };
 
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
@@ -121,6 +127,57 @@ async function run(command, args, cwd) {
   });
 }
 
+async function runCapture(command, args, cwd) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", rejectPromise);
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolvePromise(stdout.trim());
+        return;
+      }
+      rejectPromise(
+        new Error(
+          `${command} exited with ${signal ? `signal ${signal}` : `code ${code}`}${
+            stderr.trim() ? `: ${stderr.trim()}` : "."
+          }`,
+        ),
+      );
+    });
+  });
+}
+
+async function verifyDefaultStarterReference(starterRef) {
+  if (starterRef !== defaultStarterRef) {
+    return;
+  }
+
+  const remote = `https://github.com/${starterRepository}.git`;
+  const resolvedReference = await runCapture("git", [
+    "ls-remote",
+    remote,
+    `refs/tags/${starterRef}^{}`,
+  ]);
+  const resolvedCommit = resolvedReference.split(/\s+/)[0];
+  if (resolvedCommit !== defaultStarterCommit) {
+    throw new Error(
+      `Starter tag ${starterRef} resolved to ${resolvedCommit || "no commit"}, expected ${defaultStarterCommit}.`,
+    );
+  }
+}
+
 async function ensureTargetIsSafe(directory) {
   await mkdir(dirname(directory), { recursive: true });
 
@@ -137,10 +194,21 @@ async function ensureTargetIsSafe(directory) {
   }
 }
 
-async function customizeProject(directory, packageName) {
+async function customizeProject(
+  directory,
+  packageName,
+  starterRef = defaultStarterRef,
+  starterCommit = starterRef === defaultStarterRef ? defaultStarterCommit : undefined,
+) {
   const rootManifestPath = join(directory, "package.json");
   const rootManifest = JSON.parse(await readFile(rootManifestPath, "utf8"));
   rootManifest.name = packageName;
+  rootManifest.clubedge = {
+    cliVersion: packageVersion,
+    starterRepository,
+    starterRef,
+    ...(starterCommit ? { starterCommit } : {}),
+  };
 
   for (const scriptName of ["docker:build", "docker:start"]) {
     if (rootManifest.scripts?.[scriptName]) {
@@ -155,7 +223,14 @@ async function customizeProject(directory, packageName) {
   const readmePath = join(directory, "README.md");
   const readme = await readFile(readmePath, "utf8");
   const displayName = displayNameFromPackageName(packageName);
-  await writeFile(readmePath, readme.replace(/^# Clubedge Starter$/m, `# ${displayName}`));
+  const starterCommitLine = starterCommit ? `\n- Starter commit: \`${starterCommit}\`` : "";
+  const customizedReadme = readme
+    .replace(/^# Clubedge Starter$/m, `# ${displayName}`)
+    .replace(
+      /^# (.+)$/m,
+      `$&\n\n## Generated from\n\n- Starter repository: \`${starterRepository}\`\n- Starter ref: \`${starterRef}\`${starterCommitLine}\n- CLI version: \`${packageVersion}\``,
+    );
+  await writeFile(readmePath, customizedReadme);
 
   const layoutPath = join(directory, "apps", "web", "src", "app", "layout.tsx");
   const layout = await readFile(layoutPath, "utf8");
@@ -227,12 +302,13 @@ async function createProject(options) {
   await ensureTargetIsSafe(projectDirectory);
 
   const projectName = packageNameFromDirectory(projectDirectory);
+  await verifyDefaultStarterReference(options.ref);
   const source = `gh:${starterRepository}#${options.ref}`;
   const downloadSpinner = spinner();
   downloadSpinner.start(`Downloading Clubedge Starter (${options.ref})`);
   try {
     await downloadTemplate(source, { dir: projectDirectory, force: true });
-    await customizeProject(projectDirectory, projectName);
+    await customizeProject(projectDirectory, projectName, options.ref);
     downloadSpinner.stop("Starter files downloaded and configured");
   } catch (error) {
     downloadSpinner.stop("Project scaffold failed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.1.3",
+  "version": "0.1.9",
   "description": "Create a Next.js application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -20,11 +20,11 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yassine-ahmed/create-clubedge-app.git"
+    "url": "https://github.com/Clubedge/create-clubedge-app.git"
   },
-  "homepage": "https://github.com/yassine-ahmed/create-clubedge-app#readme",
+  "homepage": "https://github.com/Clubedge/create-clubedge-app#readme",
   "bugs": {
-    "url": "https://github.com/yassine-ahmed/create-clubedge-app/issues"
+    "url": "https://github.com/Clubedge/create-clubedge-app/issues"
   },
   "keywords": [
     "create-clubedge-app",