@kazzle/app 0.1.693 → 0.1.697

package/README.md

@@ -1,8 +1,8 @@
 # @kazzle/app
 
 The one versioned package for building Kazzle apps. It owns the app-facing
-TypeScript contracts, tool helpers, the Vite preview helper, the app templates,
-and the app migration codemods.
+TypeScript contracts, tool helpers, the Vite preview helper, app templates, and
+server/CLI-only app migrations.
 
 This file is the ownership doc referenced by the code comments in this package
 and in the server. Read it before changing exports, templates, or the
@@ -33,22 +33,30 @@ and the root export must stay tiny and dependency-free.
 | `@kazzle/app/client` | install-scoped client: per-install secrets, sibling component URLs | none |
 | `@kazzle/app/vite` | `kazzleAppVite` preview/runtime Vite helper | `vite` (peer, type-only) |
 | `@kazzle/app/templates` | programmatic template manifest + asset readers (server/generator only) | none |
-| `@kazzle/app/migrations` | app migration metadata + codemods (server/CLI only) | none |
+| `@kazzle/app/migrations` | versioned app upgrade metadata + codemods (server/CLI only) | none |
 
-To add an export: add the `src/*.ts` file, add it to BOTH `exports` and
-`publishConfig.exports` in `package.json`, and document it in the table above.
+To add an export: add the `src/*.ts` file, add it to `exports` in
+`package.json`, and document it in the table above.
 
 ## Build model — source in dev, dist on npm
 
 - Workspace consumers (server, tests, typecheck) resolve `exports` → raw `.ts`
   source. Bun and `tsc` read TS directly, so there is no build step for the
   monorepo. This mirrors `@kazzle/framework`.
-- The published package resolves `publishConfig.exports` → compiled `dist/*.js`
+- The published package resolves package `exports` → compiled `dist/*.js`
   + `dist/*.d.ts`, because apps installed from npm need JS + types.
-- `bun run build` (`scripts/build.ts`) emits `dist/` and copies `templates/`.
+- `bun run build` (`scripts/build.ts`) emits `dist/`; templates ship directly
+  from the package `templates/` directory.
 - Templates ship as package assets (`files: ["dist", "templates"]`) so the
   server generator reads the exact versioned template for every app it creates.
 
+## Package size
+
+Templates are package assets, not runtime imports. A generated app that imports
+`@kazzle/app`, `@kazzle/app/tools`, or `@kazzle/app/vite` only loads that
+subpath. Keep templates source-only and avoid generated artifacts so the npm
+tarball stays small; use `npm pack --dry-run` when adding large files.
+
 ## Versioning
 
 `@kazzle/app` shares the root Kazzle version during pre-launch (`package.json`

package/dist/migrations.d.ts

@@ -3,17 +3,17 @@ export type AppFileMap = Record<string, string>;
 export interface AppMigration {
     /** Unique migration id, e.g. "app-api-v0.2". Referenced by compat policy. */
     id: string;
-    /** Human range this migration upgrades FROM, e.g. "<0.2". Display + matching. */
+    /** Human range this migration upgrades from, e.g. "<0.2". */
     appliesTo: string;
     /** What the migration does. */
     description: string;
-    /** Globs the migration may edit (for the dry-run summary). */
+    /** Globs the migration may edit, for dry-run summaries. */
     files: string[];
-    /** Pure transform: returns only the files it changed (or added). */
+    /** Pure transform: returns only the files it changed or added. */
     run(files: AppFileMap): AppFileMap;
 }
 export declare const APP_MIGRATIONS: AppMigration[];
 /** Look up a migration by id. */
 export declare function getAppMigration(id: string): AppMigration | undefined;
-/** Add the `@kazzle/app` dependency to an app package.json string (idempotent). */
+/** Add the `@kazzle/app` dependency to an app package.json string. */
 export declare function addPackageDependency(pkgJson: string, version: string): string;

package/dist/migrations.js

@@ -1,27 +1,22 @@
 // @kazzle/app/migrations — versioned app migration metadata + codemods.
 //
-// SERVER/CLI ONLY. A machine-readable registry of upgrade instructions for
-// existing generated app repos — the same idea as Next codemods / Expo upgrade
-// tooling. It is NOT product data: it tells `kazzle migrate` how to rewrite an
-// app checkout when the app contract changes between package versions.
+// SERVER/CLI ONLY. This is the long-term upgrade path for existing generated
+// app repos when the app contract changes. Normal app runtime code must not
+// import this subpath.
 //
-// Codemods are PURE: they take an in-memory `{ path -> contents }` map and
-// return the changed files. The server/CLI owns reading and writing the actual
-// checkout (see the thin-CLI rule in the plan). This keeps migrations testable
-// without a filesystem and keeps fs/permission policy server-side.
+// Codemods are pure: they take an in-memory `{ path -> contents }` map and
+// return only changed files. The server/CLI owns reading and writing the actual
+// checkout so filesystem and permission policy stays server-side.
 //
 // To add a migration:
 //   1. Append an `AppMigration` to `APP_MIGRATIONS` with a unique `id`.
-//   2. Set `appliesTo` (semver-ish range string, matched by the server compat
-//      policy) and `files` (globs it may touch, for the dry-run summary).
+//   2. Set `appliesTo` and `files` for dry-run summaries.
 //   3. Implement `run` as a pure file-map transform.
-//   4. Point the server compat blocker/deprecation `migrationCommand` at the id.
-/** Rewrite a vendored `./kazzle.types` / `./kazzle.vite` import to the package. */
+//   4. Point the server compatibility blocker/deprecation text at the id.
+/** Rewrite old vendored helper imports to the versioned package. */
 function rewriteImports(contents) {
     return contents
-        // `from './kazzle.types'`, `from '../../kazzle.types'`, etc → '@kazzle/app'
         .replace(/(from\s*['"])((?:\.\.?\/)+)kazzle\.types(['"])/g, '$1@kazzle/app$3')
-        // vite helper → '@kazzle/app/vite'
         .replace(/(from\s*['"])((?:\.\.?\/)+)kazzle\.vite(['"])/g, '$1@kazzle/app/vite$3');
 }
 /** Ensure `@kazzle/app` is a dependency of the app root package.json. */
@@ -33,22 +28,16 @@ function ensurePackageDependency(pkgJson, version) {
     parsed.dependencies['@kazzle/app'] = `^${version}`;
     return JSON.stringify(parsed, null, 2) + '\n';
 }
-/**
- * v0.2: apps stop vendoring kazzle.types.ts / kazzle.vite.ts and import the
- * contracts from `@kazzle/app`. Rewrites imports, adds the dependency, and
- * deletes the vendored files (represented by an empty-string body, which the
- * server/CLI turns into a delete).
- */
 function migrateToPackageImports(files) {
     const changed = {};
     for (const [path, contents] of Object.entries(files)) {
         const base = path.split('/').pop() ?? path;
         if (base === 'kazzle.types.ts' || base === 'kazzle.vite.ts') {
-            changed[path] = ''; // empty body = delete (vendored file replaced by import)
+            changed[path] = '';
             continue;
         }
         if (path === 'package.json')
-            continue; // handled below with the version
+            continue;
         const rewritten = rewriteImports(contents);
         if (rewritten !== contents)
             changed[path] = rewritten;
@@ -59,7 +48,7 @@ export const APP_MIGRATIONS = [
     {
         id: 'app-api-v0.2',
         appliesTo: '<0.2',
-        description: 'Import Kazzle app contracts from @kazzle/app instead of vendored kazzle.types.ts / kazzle.vite.ts.',
+        description: 'Import Kazzle app contracts from @kazzle/app instead of vendored helper files.',
         files: ['**/*.ts', '**/*.tsx', 'package.json'],
         run: migrateToPackageImports,
     },
@@ -68,7 +57,7 @@ export const APP_MIGRATIONS = [
 export function getAppMigration(id) {
     return APP_MIGRATIONS.find(m => m.id === id);
 }
-/** Add the `@kazzle/app` dependency to an app package.json string (idempotent). */
+/** Add the `@kazzle/app` dependency to an app package.json string. */
 export function addPackageDependency(pkgJson, version) {
     return ensurePackageDependency(pkgJson, version);
 }

package/package.json

@@ -1,19 +1,41 @@
 {
   "name": "@kazzle/app",
-  "version": "0.1.693",
+  "version": "0.1.697",
   "description": "Contracts, tool helpers, Vite helper, and templates for building Kazzle apps.",
   "license": "UNLICENSED",
-  "repository": { "type": "git", "url": "git+https://github.com/Kazzle-ai/kazzle.git", "directory": "packages/kazzle-app" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kazzle-ai/kazzle.git",
+    "directory": "packages/kazzle-app"
+  },
   "type": "module",
   "sideEffects": false,
   "//exports": "Exports point at compiled dist so isolated consumers (Vite/Node under node_modules, deployed apps, published npm tarball) never load raw .ts — Node/Vite can't type-strip TS under node_modules. dist is a build artifact (gitignored), kept fresh by the `prepare` script below on `bun install`/`npm publish` and by the local pack step in server/templates/template-local-harness.ts.",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./tools": { "types": "./dist/tools.d.ts", "import": "./dist/tools.js" },
-    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
-    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" },
-    "./templates": { "types": "./dist/templates.d.ts", "import": "./dist/templates.js" },
-    "./migrations": { "types": "./dist/migrations.d.ts", "import": "./dist/migrations.js" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./templates": {
+      "types": "./dist/templates.d.ts",
+      "import": "./dist/templates.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations.d.ts",
+      "import": "./dist/migrations.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -35,8 +57,12 @@
     "zod": "^3 || ^4"
   },
   "peerDependenciesMeta": {
-    "vite": { "optional": true },
-    "zod": { "optional": true }
+    "vite": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^25.1.0",