@percepta/create 3.0.0

package/dist/init-Z4VGBHAK.js

@@ -0,0 +1,96 @@
+import {
+  VALID_PROJECT_TYPES,
+  isValidProjectType
+} from "./chunk-GEVZERMP.js";
+import {
+  derivePlaceholders,
+  manifestExists,
+  writeManifest
+} from "./chunk-WMJT7CB5.js";
+
+// src/commands/init.ts
+import path from "path";
+import fs from "fs-extra";
+import chalk from "chalk";
+import inquirer from "inquirer";
+async function initCommand(options) {
+  const cwd = process.cwd();
+  if (await manifestExists(cwd)) {
+    console.error(
+      chalk.red(".mosaic-template.json already exists in this directory.")
+    );
+    process.exit(1);
+  }
+  const pkgPath = path.join(cwd, "package.json");
+  let appName = path.basename(cwd);
+  if (await fs.pathExists(pkgPath)) {
+    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8"));
+    appName = pkg.name?.replace(/^@[^/]+\//, "") || appName;
+  }
+  let templateType = options.type;
+  if (templateType && !isValidProjectType(templateType)) {
+    console.error(
+      chalk.red(
+        `Invalid template type "${templateType}". Valid types: ${VALID_PROJECT_TYPES.join(", ")}`
+      )
+    );
+    process.exit(1);
+  }
+  if (!templateType) {
+    const answer = await inquirer.prompt([
+      {
+        type: "list",
+        name: "type",
+        message: "Template type:",
+        choices: ["webapp", "library"]
+      }
+    ]);
+    templateType = answer.type;
+  }
+  const templateVersion = options.templateVersion || "1.0.0";
+  const appTitle = appName.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  const manifest = {
+    templateType,
+    templateVersion,
+    templateCommit: "unknown",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    placeholders: derivePlaceholders(appName, appTitle),
+    source: {
+      templatePath: `packages/create-mosaic-module/templates/${templateType}`
+    }
+  };
+  await writeManifest(cwd, manifest);
+  const notesPath = path.join(cwd, "mosaic-template-notes.md");
+  if (!await fs.pathExists(notesPath)) {
+    await fs.writeFile(
+      notesPath,
+      `# Mosaic Divergence Notes
+
+Document intentional differences from the ${templateType} template here.
+Claude reads this file during sync to preserve your customizations.
+
+## Intentional Divergences
+
+`
+    );
+  }
+  console.log();
+  console.log(
+    chalk.green("\u2714"),
+    chalk.bold("Initialized .mosaic-template.json")
+  );
+  console.log();
+  console.log(chalk.dim("  Template:"), templateType);
+  console.log(chalk.dim("  Version:"), templateVersion);
+  console.log(chalk.dim("  App name:"), appName);
+  console.log();
+  console.log(
+    chalk.dim(
+      "Review .mosaic-template.json and mosaic-template-notes.md, then commit them."
+    )
+  );
+  console.log();
+}
+export {
+  initCommand
+};

package/dist/status-MITGDLTT.js

@@ -0,0 +1,76 @@
+import {
+  getLatestTemplateTag,
+  getTemplateVersionFromTag
+} from "./chunk-R4FWPE4A.js";
+import {
+  readManifest
+} from "./chunk-WMJT7CB5.js";
+
+// src/commands/status.ts
+import path from "path";
+import chalk from "chalk";
+async function statusCommand(options) {
+  const cwd = process.cwd();
+  try {
+    const manifest = await readManifest(cwd);
+    console.log();
+    console.log(chalk.bold("Mosaic Template Status"));
+    console.log();
+    console.log(chalk.dim("  Template type:"), manifest.templateType);
+    console.log(chalk.dim("  Current version:"), manifest.templateVersion);
+    console.log(chalk.dim("  Template commit:"), manifest.templateCommit);
+    console.log(chalk.dim("  Created:"), manifest.createdAt);
+    if (manifest.lastSyncedAt) {
+      console.log(chalk.dim("  Last synced:"), manifest.lastSyncedAt);
+    }
+    const rawPath = options.mosaicTemplatePath || process.env.MOSAIC_TEMPLATE_PATH;
+    const mosaicTemplatePath = rawPath ? path.resolve(rawPath) : void 0;
+    if (mosaicTemplatePath) {
+      const latestTag = getLatestTemplateTag(
+        manifest.templateType,
+        mosaicTemplatePath
+      );
+      if (latestTag) {
+        const latestVersion = getTemplateVersionFromTag(latestTag);
+        console.log(chalk.dim("  Latest version:"), latestVersion);
+        console.log();
+        if (latestVersion !== manifest.templateVersion) {
+          console.log(
+            chalk.yellow(
+              `  Update available: ${manifest.templateVersion} \u2192 ${latestVersion}`
+            )
+          );
+          console.log(
+            chalk.dim("  Run:"),
+            `create sync --mosaic-template-path ${mosaicTemplatePath}`
+          );
+        } else {
+          console.log(chalk.green("  Up to date"));
+        }
+      } else {
+        console.log();
+        console.log(
+          chalk.yellow("  No template tags found in mosaic repo.")
+        );
+        console.log(
+          chalk.dim("  Run:"),
+          `cd ${mosaicTemplatePath} && pnpm template:tag`
+        );
+      }
+    } else {
+      console.log();
+      console.log(
+        chalk.dim(
+          "  Use --mosaic-template-path or set MOSAIC_TEMPLATE_PATH to check for updates"
+        )
+      );
+    }
+    console.log();
+  } catch (error) {
+    console.error(chalk.red(error.message));
+    process.exit(1);
+  }
+}
+export {
+  statusCommand
+};

package/dist/sync-J4SFZHDX.js

@@ -0,0 +1,136 @@
+import {
+  getLatestTemplateTag,
+  getTemplateDiff,
+  getTemplateVersionFromTag
+} from "./chunk-R4FWPE4A.js";
+import {
+  readManifest,
+  resolveMosaicTemplatePath
+} from "./chunk-WMJT7CB5.js";
+
+// src/commands/sync.ts
+import path from "path";
+import fs from "fs-extra";
+import chalk from "chalk";
+function generateSyncContext(manifest, toVersion, diff, notes) {
+  let content = `# Mosaic Sync Context
+
+## App Info
+- **Template:** ${manifest.templateType}
+- **Current version:** ${manifest.templateVersion}
+- **Target version:** ${toVersion}
+
+## Placeholder Mappings
+
+When applying template changes, replace these placeholder tokens with the actual values:
+
+| Placeholder | Value |
+|------------|-------|
+${Object.entries(manifest.placeholders).map(([k, v]) => `| \`${k}\` | \`${v}\` |`).join("\n")}
+
+## Template Changes (${manifest.templateVersion} \u2192 ${toVersion})
+
+\`\`\`diff
+${diff}
+\`\`\`
+`;
+  if (notes.trim()) {
+    content += `
+## Divergence Notes (from mosaic-template-notes.md)
+
+${notes}
+`;
+  }
+  content += `
+## Instructions
+
+1. Apply the template changes above to this app
+2. When you see placeholder tokens (e.g. \`__APP_NAME__\`), replace them with the actual values from the mapping table
+3. Check the divergence notes \u2014 preserve intentional divergences
+4. For files not modified locally: apply changes directly
+5. For files modified locally: merge intelligently, preserving local customizations
+6. After applying all changes, run: \`pnpm install && pnpm build && pnpm lint\`
+7. Update \`.mosaic-template.json\`: set \`templateVersion\` to \`"${toVersion}"\` and update \`templateCommit\`
+8. If you made decisions about merge conflicts, add notes to \`mosaic-template-notes.md\`
+9. Delete this file (\`.mosaic-sync-context.md\`) when done
+`;
+  return content;
+}
+async function syncCommand(options) {
+  const cwd = process.cwd();
+  try {
+    const manifest = await readManifest(cwd);
+    const mosaicTemplatePath = resolveMosaicTemplatePath(options);
+    const fromTag = `template/${manifest.templateType}/${manifest.templateVersion}`;
+    let toTag;
+    if (options.to) {
+      toTag = `template/${manifest.templateType}/${options.to}`;
+    } else {
+      const latest = getLatestTemplateTag(
+        manifest.templateType,
+        mosaicTemplatePath
+      );
+      if (!latest) {
+        console.error(
+          chalk.red(
+            "No template tags found. Run 'pnpm template:tag' in the mosaic repo first."
+          )
+        );
+        process.exit(1);
+      }
+      toTag = latest;
+    }
+    const toVersion = getTemplateVersionFromTag(toTag);
+    if (toVersion === manifest.templateVersion) {
+      console.log(chalk.green("Already up to date."));
+      return;
+    }
+    const diff = getTemplateDiff(
+      mosaicTemplatePath,
+      manifest.source.templatePath,
+      fromTag,
+      toTag
+    );
+    if (!diff.trim()) {
+      console.log(
+        chalk.green("No template file changes between versions.")
+      );
+      return;
+    }
+    const notesPath = path.join(cwd, "mosaic-template-notes.md");
+    let notes = "";
+    if (await fs.pathExists(notesPath)) {
+      notes = await fs.readFile(notesPath, "utf-8");
+    }
+    const context = generateSyncContext(manifest, toVersion, diff, notes);
+    const contextPath = path.join(cwd, ".mosaic-sync-context.md");
+    await fs.writeFile(contextPath, context);
+    console.log();
+    console.log(chalk.bold("Sync Context Generated"));
+    console.log();
+    console.log(chalk.dim("  From:"), manifest.templateVersion);
+    console.log(chalk.dim("  To:"), toVersion);
+    console.log(chalk.dim("  Context file:"), ".mosaic-sync-context.md");
+    console.log();
+    console.log("Next steps:");
+    console.log(
+      chalk.dim("  1."),
+      "Open Claude Code in this directory"
+    );
+    console.log(
+      chalk.dim("  2."),
+      'Tell Claude: "Read .mosaic-sync-context.md and apply the template changes"'
+    );
+    console.log(
+      chalk.dim("  3."),
+      "Review Claude's changes, then delete .mosaic-sync-context.md"
+    );
+    console.log();
+  } catch (error) {
+    console.error(chalk.red(error.message));
+    process.exit(1);
+  }
+}
+export {
+  syncCommand
+};

package/dist/upstream-AQI7P4EU.js

@@ -0,0 +1,144 @@
+import {
+  getFileAtTag
+} from "./chunk-R4FWPE4A.js";
+import {
+  readManifest,
+  resolveMosaicTemplatePath
+} from "./chunk-WMJT7CB5.js";
+
+// src/commands/upstream.ts
+import path from "path";
+import fs from "fs-extra";
+import chalk from "chalk";
+async function generateUpstreamContext(manifest, mosaicTemplatePath, tag, appDir, files) {
+  let content = `# Mosaic Upstream Context
+
+## App Info
+- **App name:** ${manifest.placeholders.__APP_NAME__ || "unknown"}
+- **Template:** ${manifest.templateType}
+- **Template version:** ${manifest.templateVersion}
+
+## Placeholder Mappings
+
+When generalizing app code back to template, replace these values with placeholder tokens:
+
+| Value | Placeholder |
+|-------|------------|
+${Object.entries(manifest.placeholders).sort((a, b) => b[1].length - a[1].length).map(([k, v]) => `| \`${v}\` | \`${k}\` |`).join("\n")}
+
+## Files to Review
+
+`;
+  for (const file of files) {
+    const appFilePath = path.resolve(appDir, file);
+    const templateRelPath = `${manifest.source.templatePath}/${file}`;
+    const appContent = await fs.pathExists(appFilePath) ? await fs.readFile(appFilePath, "utf-8") : null;
+    const templateContent = getFileAtTag(
+      mosaicTemplatePath,
+      tag,
+      templateRelPath
+    );
+    content += `### ${file}
+
+`;
+    if (!templateContent && appContent) {
+      content += `**New file** (not in template at ${manifest.templateVersion})
+
+`;
+      content += `\`\`\`
+${appContent}
+\`\`\`
+
+`;
+    } else if (templateContent && !appContent) {
+      content += `**Deleted** (exists in template but not in app)
+
+`;
+    } else if (appContent && templateContent) {
+      content += `**App version:**
+\`\`\`
+${appContent}
+\`\`\`
+
+`;
+      content += `**Template version (at ${manifest.templateVersion}):**
+\`\`\`
+${templateContent}
+\`\`\`
+
+`;
+    } else {
+      content += `**Not found** (file does not exist in app or template)
+
+`;
+    }
+  }
+  content += `## Instructions
+
+1. Review each file above
+2. Determine which changes are generalizable (useful for all apps) vs app-specific
+3. For generalizable changes: apply them to the template at \`${manifest.source.templatePath}/\`
+4. When applying, replace app-specific values with placeholders using the mapping table above (replace longest values first)
+5. After applying, bump the version in \`packages/create-mosaic-module/template-versions.json\`
+6. Run \`pnpm template:tag\` to create the new version tag
+7. Delete this file (\`.mosaic-upstream-context.md\`) when done
+`;
+  return content;
+}
+async function upstreamCommand(options) {
+  const cwd = process.cwd();
+  try {
+    const manifest = await readManifest(cwd);
+    const mosaicTemplatePath = resolveMosaicTemplatePath(options);
+    if (!options.files || options.files.length === 0) {
+      console.error(
+        chalk.red("Specify files with --files <file1> <file2> ...")
+      );
+      console.log(
+        chalk.dim(
+          "  Example: create upstream --files src/config/getEnvConfig.ts"
+        )
+      );
+      process.exit(1);
+    }
+    const tag = `template/${manifest.templateType}/${manifest.templateVersion}`;
+    const context = await generateUpstreamContext(
+      manifest,
+      mosaicTemplatePath,
+      tag,
+      cwd,
+      options.files
+    );
+    const contextPath = path.join(cwd, ".mosaic-upstream-context.md");
+    await fs.writeFile(contextPath, context);
+    console.log();
+    console.log(chalk.bold("Upstream Context Generated"));
+    console.log();
+    console.log(chalk.dim("  Files:"), options.files.join(", "));
+    console.log(
+      chalk.dim("  Context file:"),
+      ".mosaic-upstream-context.md"
+    );
+    console.log();
+    console.log("Next steps:");
+    console.log(
+      chalk.dim("  1."),
+      "Open Claude Code in the mosaic repo"
+    );
+    console.log(
+      chalk.dim("  2."),
+      `Tell Claude: "Read ${path.resolve(cwd, ".mosaic-upstream-context.md")} and apply generalizable changes to the template"`
+    );
+    console.log(
+      chalk.dim("  3."),
+      "Review Claude's changes to the template"
+    );
+    console.log();
+  } catch (error) {
+    console.error(chalk.red(error.message));
+    process.exit(1);
+  }
+}
+export {
+  upstreamCommand
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@percepta/create",
+  "version": "3.0.0",
+  "description": "Scaffold a new Mosaic package",
+  "type": "module",
+  "bin": {
+    "create": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "template-versions.json"
+  ],
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "fs-extra": "^11.3.0",
+    "inquirer": "^12.5.0",
+    "ora": "^8.2.0",
+    "validate-npm-package-name": "^6.0.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.1.0",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.0",
+    "@percepta/build": "0.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "create",
+    "template",
+    "nextjs",
+    "mosaic",
+    "percepta",
+    "scaffold",
+    "cli"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "sync-template": "tsx scripts/sync-template.ts",
+    "template:tag": "tsx scripts/template-tag.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:template": "bash scripts/test-template.sh"
+  }
+}

package/template-versions.json

@@ -0,0 +1,4 @@
+{
+  "webapp": "1.0.0",
+  "library": "1.0.0"
+}

package/templates/library/README.md

@@ -0,0 +1,30 @@
+# __APP_TITLE__
+
+A TypeScript library package.
+
+## Installation
+
+```bash
+pnpm add __APP_NAME__
+```
+
+## Development
+
+```bash
+# Build the library
+pnpm build
+
+# Watch mode for development
+pnpm dev
+
+# Run linting
+pnpm lint
+```
+
+## Usage
+
+```typescript
+import { hello } from "__APP_NAME__";
+
+console.log(hello("World"));
+```

package/templates/library/eslint.config.js

@@ -0,0 +1,10 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ["node_modules/**", "dist/**"],
+  }
+);

package/templates/library/gitignore.template

@@ -0,0 +1,18 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

package/templates/library/package.json.template

@@ -0,0 +1,29 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "__APP_TITLE__",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "echo \"No tests configured yet\""
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "eslint": "^9.18.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.0"
+  }
+}

package/templates/library/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * __APP_TITLE__
+ *
+ * Add your library exports here.
+ */
+
+export function hello(name: string): string {
+  return `Hello, ${name}!`;
+}

package/templates/library/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/monorepo/README.md

@@ -0,0 +1,41 @@
+# __APP_TITLE__
+
+A monorepo powered by [pnpm workspaces](https://pnpm.io/workspaces).
+
+## Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run development mode for all packages
+pnpm dev
+
+# Build all packages
+pnpm build
+
+# Run tests
+pnpm test
+
+# Lint all packages
+pnpm lint
+```
+
+## Structure
+
+```
+packages/
+  └── your-package/    # Add your packages here
+```
+
+## Adding a new package
+
+Create a new directory in `packages/` with its own `package.json`:
+
+```bash
+mkdir packages/my-package
+cd packages/my-package
+pnpm init
+```
+
+Then run `pnpm install` from the root to link the workspace.

package/templates/monorepo/eslint.config.js

@@ -0,0 +1,10 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ["**/node_modules/**", "**/dist/**"],
+  }
+);