@percepta/create 3.0.0

package/README.md

@@ -0,0 +1,93 @@
+# @percepta/create
+
+Scaffold and manage Mosaic packages.
+
+## Usage
+
+```bash
+npx @percepta/create
+```
+
+That's it. The CLI prompts you for the project name and (depending on context) whether it's a webapp. Defaults yield a running app — sign in as `admin@example.com` / `password`.
+
+## Options (mostly for automation)
+
+The bare command above is the canonical UX. The flags below exist for tests and other automation, not for routine use:
+
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Package type: `monorepo`, `webapp`, or `library` (skips the type prompt) |
+| `--name <name>` | Project name (skips the name prompt) |
+| `--skip-install` | Skip dependency installation, which also skips the auto-run setup + dev + browser, leaving you with manual next-steps |
+| `-y, --yes` | Skip all prompts; requires `--name` |
+
+## Subcommands
+
+- `create` (default) — scaffold a new Mosaic package
+- `status` — show template sync status for the current app
+- `sync` — generate downstream sync context (template → app)
+- `upstream` — generate upstream context (app → template)
+- `init` — add `.mosaic-template.json` to an existing app
+
+## Project types
+
+`create` auto-detects whether you're inside an existing pnpm monorepo (by walking up for `pnpm-workspace.yaml`) and changes its prompts accordingly:
+
+- **Outside a monorepo** — pick `Monorepo` (default) or `Library`. If `Monorepo`, you're asked "Initialize with a webapp?" (Y/n, default Y). Picking the webapp option scaffolds a monorepo with a webapp inside `packages/<name>/`. Declining gives you an empty monorepo.
+- **Inside a monorepo** — pick `Webapp` (default) or `Library` to add a new package under the workspace pattern.
+
+## Happy-path: zero-friction webapp
+
+When you scaffold a webapp (the default flow), `create` automatically runs:
+
+1. `pnpm install` (at the monorepo root)
+2. `pnpm run setup` — Docker Compose Postgres + Drizzle migrations + seed user
+3. `pnpm dev` — Next.js dev server
+4. Opens the served URL in your default browser
+
+Sign in as `admin@example.com` / `password` to start building.
+
+To bail out of the auto-run and get manual next-steps instead, pass `--skip-install`. Then you can run install / setup / dev yourself when ready.
+
+The `webapp` template ships with:
+
+- **Next.js 15** with App Router
+- **Authentication** via Better Auth
+- **Database** with PostgreSQL and Drizzle ORM
+- **Type-safe API** with tRPC
+- **Background Jobs** with Inngest
+- **Observability** with OpenTelemetry, Langfuse, and Grafana Faro
+- **Styling** with Tailwind CSS v4
+
+The `library` template ships with TypeScript, ESLint, and a minimal `src/index.ts`.
+
+The `monorepo` template ships with `pnpm-workspace.yaml`, root scripts (`dev`, `build`, `lint`, `test`), strict `tsconfig.json`, flat-config ESLint, and an empty `packages/` directory.
+
+## Development
+
+### Building the CLI
+
+```bash
+pnpm build
+```
+
+### Testing locally
+
+```bash
+pnpm build
+npm link
+create test-app
+```
+
+### Syncing template files
+
+When the base template is updated, sync the changes:
+
+```bash
+pnpm sync-template
+```
+
+## Publishing
+
+Publishing is automated via changesets on merge to `main`. See the repo-root
+`.changeset/README.md` and `.github/workflows/build-and-publish.yml`.

package/dist/chunk-GEVZERMP.js

@@ -0,0 +1,108 @@
+// src/utils/prompts.ts
+import path from "path";
+import inquirer from "inquirer";
+
+// src/utils/validate.ts
+import validateNpmPackageName from "validate-npm-package-name";
+function validateProjectName(name) {
+  const result = validateNpmPackageName(name);
+  if (!result.validForNewPackages) {
+    const errors = [...result.errors || [], ...result.warnings || []];
+    return {
+      valid: false,
+      error: errors[0] || "Invalid package name"
+    };
+  }
+  return { valid: true };
+}
+
+// src/utils/case-converters.ts
+function toKebabCase(str) {
+  return str.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function toTitleCase(str) {
+  return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function toSnakeCase(str) {
+  return str.replace(/-/g, "_");
+}
+
+// src/utils/prompts.ts
+var VALID_PROJECT_TYPES = ["monorepo", "webapp", "library"];
+function isValidProjectType(value) {
+  return typeof value === "string" && VALID_PROJECT_TYPES.includes(value);
+}
+async function promptName(message) {
+  const { name } = await inquirer.prompt([
+    {
+      type: "input",
+      name: "name",
+      message,
+      filter: toKebabCase,
+      validate: (input) => {
+        const result = validateProjectName(toKebabCase(input));
+        return result.valid || result.error || "Invalid project name";
+      }
+    }
+  ]);
+  return name;
+}
+async function promptOutsideMonorepoType() {
+  const { webapp } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "webapp",
+      message: "Initialize with a webapp?",
+      default: true
+    }
+  ]);
+  return webapp ? "webapp" : "monorepo";
+}
+async function promptInsideMonorepoType() {
+  const { projectType } = await inquirer.prompt([
+    {
+      type: "rawlist",
+      name: "projectType",
+      message: "What kind of package?",
+      // inquirer v12 / @inquirer/rawlist v5 matches `default` against the
+      // choice's `value`, not its index. `default: 0` would be a no-op.
+      default: "webapp",
+      choices: [
+        { name: "Webapp  \u2014 A Next.js webapp", value: "webapp" },
+        { name: "Library \u2014 A TypeScript library", value: "library" }
+      ]
+    }
+  ]);
+  return projectType;
+}
+async function promptProjectDetails(defaults) {
+  const inMonorepo = defaults.monorepoContext?.found ?? false;
+  let projectType;
+  let finalName;
+  if (inMonorepo) {
+    projectType = defaults.projectType ?? await promptInsideMonorepoType();
+    finalName = defaults.name || await promptName("Package name?");
+  } else {
+    finalName = defaults.name || await promptName("Project name?");
+    projectType = defaults.projectType ?? await promptOutsideMonorepoType();
+  }
+  const finalTitle = finalName ? toTitleCase(finalName) : "";
+  const finalDirectory = !inMonorepo && finalName ? path.resolve(process.cwd(), finalName) : "";
+  return {
+    projectType,
+    directory: finalDirectory,
+    name: finalName,
+    title: finalTitle,
+    installDeps: !defaults.skipInstall
+  };
+}
+
+export {
+  validateProjectName,
+  toKebabCase,
+  toTitleCase,
+  toSnakeCase,
+  VALID_PROJECT_TYPES,
+  isValidProjectType,
+  promptProjectDetails
+};

package/dist/chunk-R4FWPE4A.js

@@ -0,0 +1,49 @@
+// src/utils/git-ops.ts
+import { execFileSync } from "child_process";
+function toGitPath(p) {
+  return p.replace(/\\/g, "/");
+}
+function getLatestTemplateTag(type, repoPath) {
+  try {
+    const tags = execFileSync(
+      "git",
+      ["tag", "-l", `template/${type}/*`, "--sort=-v:refname"],
+      { cwd: repoPath, encoding: "utf-8" }
+    ).trim();
+    if (!tags) return null;
+    return tags.split("\n")[0];
+  } catch {
+    return null;
+  }
+}
+function getTemplateVersionFromTag(tag) {
+  const parts = tag.split("/");
+  return parts[parts.length - 1];
+}
+function getTemplateDiff(repoPath, templatePath, fromTag, toTag) {
+  return execFileSync(
+    "git",
+    ["diff", `${fromTag}..${toTag}`, "--", toGitPath(templatePath)],
+    {
+      cwd: repoPath,
+      encoding: "utf-8"
+    }
+  );
+}
+function getFileAtTag(repoPath, tag, filePath) {
+  try {
+    return execFileSync("git", ["show", `${tag}:${toGitPath(filePath)}`], {
+      cwd: repoPath,
+      encoding: "utf-8"
+    });
+  } catch {
+    return null;
+  }
+}
+
+export {
+  getLatestTemplateTag,
+  getTemplateVersionFromTag,
+  getTemplateDiff,
+  getFileAtTag
+};

package/dist/chunk-WMJT7CB5.js

@@ -0,0 +1,57 @@
+// src/utils/manifest.ts
+import path from "path";
+import fs from "fs-extra";
+var MANIFEST_FILENAME = ".mosaic-template.json";
+function getManifestPath(dir) {
+  return path.join(dir, MANIFEST_FILENAME);
+}
+async function readManifest(dir) {
+  const manifestPath = getManifestPath(dir);
+  if (!await fs.pathExists(manifestPath)) {
+    throw new Error(
+      `No ${MANIFEST_FILENAME} found in ${dir}. Run 'create init' to create one.`
+    );
+  }
+  const content = await fs.readFile(manifestPath, "utf-8");
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON in ${MANIFEST_FILENAME}: ${error.message}`
+    );
+  }
+}
+async function writeManifest(dir, manifest) {
+  const manifestPath = getManifestPath(dir);
+  await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+}
+async function manifestExists(dir) {
+  return fs.pathExists(getManifestPath(dir));
+}
+function derivePlaceholders(appName, appTitle) {
+  const nameSnake = appName.replace(/-/g, "_");
+  return {
+    __APP_NAME__: appName,
+    __APP_TITLE__: appTitle,
+    __DB_NAME__: nameSnake + "_db",
+    __APP_NAME_UPPER__: appName.toUpperCase(),
+    __APP_NAME_SNAKE__: nameSnake
+  };
+}
+function resolveMosaicTemplatePath(options) {
+  if (options.mosaicTemplatePath)
+    return path.resolve(options.mosaicTemplatePath);
+  if (process.env.MOSAIC_TEMPLATE_PATH)
+    return path.resolve(process.env.MOSAIC_TEMPLATE_PATH);
+  throw new Error(
+    "Mosaic repo path required. Use --mosaic-template-path or set MOSAIC_TEMPLATE_PATH."
+  );
+}
+
+export {
+  readManifest,
+  writeManifest,
+  manifestExists,
+  derivePlaceholders,
+  resolveMosaicTemplatePath
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node