Release v0.1.0: CLI --local, templates, and publishing docs.

Add --local for monorepo file: links, graceful Ctrl+C via withSpinner,
template-bound module selection with optional customize, structure flag
docs, and publishing guide plus restricted GitHub Packages publish.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: aglago

.cursor/skills/genesis/SKILL.md

@@ -41,12 +41,12 @@ genesis update
 | Monolith (default) | `--structure monolith` | Next.js app at repo root |
 | Monorepo | `--structure monorepo` | Turborepo, app in `apps/web/` |
 
-| Template | Default modules |
-|----------|-----------------|
-| `custom` | none |
-| `informational-site` | branding |
-| `saas-app` | auth, branding, payments, dashboard |
-| `ecommerce` | payments, dashboard |
+| Template | Bundled modules | Module selection |
+|----------|-----------------|------------------|
+| `custom` | none | Full picker always |
+| `informational-site` | branding | Auto; Customize? for emails/analytics. Blocks auth, payments, dashboard |
+| `saas-app` | auth, branding, payments, dashboard, notifications | Auto; Customize? for emails, uploads, analytics |
+| `ecommerce` | payments, dashboard | Auto; Customize? for auth, branding, uploads, etc. |
 
 **Monorepo dev CLI:** `node cli/dist/index.js create my-app` (after `npm run build` at repo root)
 

.github/workflows/publish.yml

@@ -25,6 +25,6 @@ jobs:
 
       - run: npm run build
 
-      - run: npm publish --workspaces --if-present
+      - run: npm publish --workspaces --if-present --access restricted
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.npmrc.example

@@ -0,0 +1,5 @@
+# Point @genesis packages at GitHub Packages.
+# Copy to your project root or ~/.npmrc and set GITHUB_TOKEN.
+
+@genesis:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

README.md

@@ -21,10 +21,10 @@ Enable developers to create production-ready web applications in minutes by asse
 npm install
 npm run build
 
-# Create a new project
-node cli/dist/index.js create my-app
+# Create a new project (link local packages while unpublished)
+node cli/dist/index.js create my-app --local
 
-# Or after publishing
+# Or after publishing to GitHub Packages (see docs/publishing.md)
 npx @genesis/cli create my-app
 ```
 

USAGE.md

@@ -12,6 +12,7 @@ Documentation index for using Genesis. Detailed guides live in the [`docs/`](doc
 | [docs/configuration.md](docs/configuration.md) | Environment variables and `genesis.config.ts` |
 | [docs/workflows.md](docs/workflows.md) | Portfolio, SaaS, e-commerce, incremental setups |
 | [docs/troubleshooting.md](docs/troubleshooting.md) | Common errors and fixes |
+| [docs/publishing.md](docs/publishing.md) | Local `--local` linking, Git tags, GitHub Packages |
 
 ## Modules
 
@@ -29,11 +30,11 @@ Documentation index for using Genesis. Detailed guides live in the [`docs/`](doc
 ## Quick Reference
 
 ```bash
-# Create a project
-genesis create my-app
+# Create a project (local monorepo — while packages are unpublished)
+node cli/dist/index.js create my-app --local
 
 # Non-interactive SaaS starter
-genesis create acme -y -t saas-app
+genesis create acme -y -t saas-app --local
 
 # Add a module to an existing project
 genesis add notifications

cli/src/__tests__/exit.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { isUserCancellation } from "../utils/exit.js";
+
+describe("exit utils", () => {
+  it("detects ExitPromptError from inquirer", () => {
+    expect(isUserCancellation({ name: "ExitPromptError", message: "User force closed the prompt" })).toBe(true);
+  });
+
+  it("detects force closed prompt message", () => {
+    expect(isUserCancellation(new Error("User force closed the prompt with 0 null"))).toBe(true);
+  });
+
+  it("returns false for regular errors", () => {
+    expect(isUserCancellation(new Error("Something broke"))).toBe(false);
+    expect(isUserCancellation(null)).toBe(false);
+  });
+});

cli/src/__tests__/local-packages.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import fs from "fs-extra";
+import path from "path";
+import os from "os";
+import { resolveLocalPackageRef, usesLocalPackages } from "../utils/local-packages.js";
+import { getGenesisRoot } from "../utils/manifests.js";
+
+describe("local-packages", () => {
+  it("resolves file: paths relative to the target app", () => {
+    const genesisRoot = getGenesisRoot();
+    const targetDir = path.join(genesisRoot, "tmp-test-app");
+
+    const ref = resolveLocalPackageRef(targetDir, "@genesis/branding");
+    expect(ref).toBe("file:../packages/branding");
+  });
+
+  it("detects file: linked dependencies", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "genesis-local-"));
+    await fs.writeJson(path.join(dir, "package.json"), {
+      dependencies: {
+        "@genesis/core": "file:../packages/core",
+        next: "^15.0.0",
+      },
+    });
+
+    expect(usesLocalPackages(dir)).toBe(true);
+    await fs.remove(dir);
+  });
+
+  it("returns false when using registry versions", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "genesis-local-"));
+    await fs.writeJson(path.join(dir, "package.json"), {
+      dependencies: { "@genesis/core": "*" },
+    });
+
+    expect(usesLocalPackages(dir)).toBe(false);
+    await fs.remove(dir);
+  });
+});

cli/src/__tests__/templates.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import {
+  getTemplateDefinition,
+  resolveModulesFromFlag,
+  mergeTemplateModules,
+  getSelectableModulesForTemplate,
+} from "../utils/templates.js";
+
+describe("template definitions", () => {
+  it("informational-site requires branding and excludes auth", () => {
+    const def = getTemplateDefinition("informational-site");
+    expect(def.requiredModules).toEqual(["branding"]);
+    expect(def.excludedModules).toContain("auth");
+    expect(def.excludedModules).toContain("payments");
+  });
+
+  it("saas-app includes notifications per PRD", () => {
+    const def = getTemplateDefinition("saas-app");
+    expect(def.requiredModules).toContain("notifications");
+    expect(def.requiredModules).toContain("auth");
+  });
+
+  it("custom allows free choice", () => {
+    expect(getTemplateDefinition("custom").freeChoice).toBe(true);
+  });
+
+  it("merges required modules when customizing", () => {
+    const result = mergeTemplateModules("informational-site", ["branding", "emails"]);
+    expect(result).toEqual(["branding", "emails"]);
+  });
+
+  it("blocks excluded modules when customizing", () => {
+    const result = mergeTemplateModules("informational-site", ["branding", "auth"]);
+    expect(result).toEqual(["branding"]);
+  });
+
+  it("resolveModulesFromFlag always includes required", () => {
+    const result = resolveModulesFromFlag("ecommerce", ["auth"]);
+    expect(result).toContain("payments");
+    expect(result).toContain("dashboard");
+    expect(result).toContain("auth");
+  });
+
+  it("resolveModulesFromFlag filters excluded on informational", () => {
+    const result = resolveModulesFromFlag("informational-site", ["auth", "emails"]);
+    expect(result).toEqual(["branding", "emails"]);
+  });
+
+  it("getSelectableModulesForTemplate hides excluded", () => {
+    const selectable = getSelectableModulesForTemplate("informational-site", [
+      "auth",
+      "branding",
+      "emails",
+      "payments",
+    ]);
+    expect(selectable).toContain("branding");
+    expect(selectable).toContain("emails");
+    expect(selectable).not.toContain("auth");
+    expect(selectable).not.toContain("payments");
+  });
+});

cli/src/commands/add.ts

@@ -1,6 +1,5 @@
 import path from "path";
 import chalk from "chalk";
-import ora from "ora";
 import { confirm } from "@inquirer/prompts";
 import type { ModuleId } from "@genesis/core";
 import { resolveModuleOrder } from "@genesis/core";
@@ -13,8 +12,14 @@ import {
 } from "../utils/scaffold.js";
 import { linkGenesisPackages } from "../utils/template.js";
 import { findGenesisAppDir } from "../utils/structure.js";
+import { withSpinner } from "../utils/exit.js";
+import { usesLocalPackages } from "../utils/local-packages.js";
 
-export async function addCommand(moduleName: string): Promise<void> {
+export interface AddOptions {
+  local?: boolean;
+}
+
+export async function addCommand(moduleName: string, options: AddOptions = {}): Promise<void> {
   const manifests = await loadAllManifests();
   const manifest = getManifestById(moduleName as ModuleId);
 
@@ -38,14 +43,18 @@ export async function addCommand(moduleName: string): Promise<void> {
   if (missingDeps.length > 0) {
     console.log(chalk.yellow(`Installing dependencies first: ${missingDeps.join(", ")}`));
     for (const dep of missingDeps) {
-      await addCommand(dep);
+      await addCommand(dep, options);
     }
   }
 
-  const spinner = ora(`Adding ${manifest.name}...`).start();
+  const useLocal = options.local ?? usesLocalPackages(targetDir);
 
-  try {
-    linkGenesisPackages(targetDir, [manifest.npmPackage, "@genesis/core", "@genesis/database", "@genesis/ui"]);
+  await withSpinner(`Adding ${manifest.name}...`, async (spinner) => {
+    linkGenesisPackages(
+      targetDir,
+      [manifest.npmPackage, "@genesis/core", "@genesis/database", "@genesis/ui"],
+      { local: useLocal },
+    );
 
     const allModuleIds = [...existing, moduleName] as ModuleId[];
     const orderedIds = resolveModuleOrder(allModuleIds, manifests);
@@ -75,8 +84,5 @@ export async function addCommand(moduleName: string): Promise<void> {
         console.log(chalk.dim(`    ${envVar.key} — ${envVar.description}`));
       }
     }
-  } catch (error) {
-    spinner.fail(chalk.red(`Failed to add ${moduleName}`));
-    throw error;
-  }
+  });
 }