@saasicat/cli 1.0.0-rc.0 → 1.0.0-rc.10

package/README.md

@@ -1,5 +1,7 @@
 # @saasicat/cli
 
+## What this is
+
 Cross-cutting helpers for consumer CLIs. Provides:
 
 - `CliContextService` — identity / MFA / production-confirm / audit-tag
@@ -12,6 +14,16 @@ Cross-cutting helpers for consumer CLIs. Provides:
 
 Spec: [`cli-conventions.md`][conventions] in `@saasicat/spec`.
 
+## What this is not
+
+Not a CLI. There is no binary here: these are `nest-commander` flows and
+services you register in **your** application's CLI, so they run with your
+DI container, your database connection and your configuration.
+
+Not the schema tooling either — `saasicat schema apply|check|migrate` and
+`saasicat init` ship in the `saasicat` binary of this package's `bin`, and
+are documented in the quickstart rather than here.
+
 ## Plugin Architecture
 
 Consumer CLIs are NestJS-Standalone applications based on
@@ -30,7 +42,25 @@ import { PrismaUserPortAdapter } from './adapters/prisma-user-port';
 @Module({
     imports: [
         PrismaModule,
-        PlanCatalogModule.forRoot({ path: './config/plans.yaml' }),
+        PlanCatalogModule.forRoot({
+            app: { name: 'MyApp' },
+            currency: 'EUR',
+            vatRate: 19,
+            // Spelled out here like the three above it. In an application
+            // these come from `loadPlanCatalogFromFile('config/saas.yaml')` —
+            // the settings are never in the database, so the file is the only
+            // place they can come from.
+            tenantBilling: {
+                cancellationNoticeDays: { monthly: 0, yearly: 0 },
+                selfServiceBlockedPlans: { asTarget: [], asSource: [] },
+            },
+            // The catalogue is read from the database, not from a file — the
+            // CLI's `plan-catalog import` puts it there.
+            sink: {
+                useFactory: (p) => new PrismaPlanCatalogReadSink(p),
+                inject: [PrismaService],
+            },
+        }),
         AdminModule.forRoot({
             mfaPort: { useFactory: (p) => new PrismaMfaAdapter(p), inject: [PrismaService] },
             auditPort: { useFactory: (p) => new PrismaAuditAdapter(p), inject: [PrismaService] },
@@ -141,3 +171,8 @@ Per [`cli-conventions.md`][conventions] §6:
 | 99   | internal                                |
 
 [conventions]: https://github.com/uelker70/saasicat/blob/main/packages/spec/cli-conventions.md
+
+## Next
+
+- [Extend your CLI](../../docs/guides/extend-your-cli.md) — registering these flows in your app
+- [Quickstart](../../docs/quickstart.md) — `saasicat init`, `schema apply`, `schema check`

package/bin/saasicat.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // `saasicat` — bootstrap CLI for the SaaSiCat framework.
 // naming-history: the codemod help below names the pre-1.0 spellings it rewrites.
+// project-key-history: `codemod v1-project-key` is named after what it removes.
 //
 // Sub-commands:
 //   schema apply [--prisma-schema=PATH] [--fragments=01,02,03]
@@ -16,10 +17,12 @@
 //       apply --all, then `prisma migrate dev`, then append the constraints
 //       Prisma's DSL cannot express to the migration it just wrote.
 //
-//   init --project-key=X --quota=key:Model [--quota=…]... [--app-name=X] [--api-base=X]
+//   init --app-key=X --quota=key:Model [--quota=…]... [--app-name=X] [--api-base=X]
 //   codemod v1-imports [--dir=X] [--dry-run]
 //   codemod v1-rename  [--dir=X] [--dry-run]
-//   codemod v1         [--dir=X] [--dry-run]   — both, in that order
+//   codemod v1-project-key [--dir=X] [--dry-run]
+//   codemod v1-moved-settings [--dir=X]         — and a `dbCatalog` still carrying values
+//   codemod v1         [--dir=X] [--dry-run]   — all four, in that order
 //        [--skip-hasher] [--dry-run] [--dir=.]
 //       Writes the platform wiring — config, persistence, manifest
 //       contribution, admin module, one provider per quota — and adds
@@ -27,7 +30,7 @@
 
 import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
@@ -43,18 +46,30 @@ import {
     applyTokens,
     constraintsFor,
     checkSchema,
-    extractModelBlocks,
+    extractFragmentBlocks,
     findFkPointers,
     hasConstraints,
-    assertValidProjectKey,
+    assertValidAppKey,
+    judgeModuleResolution,
+    readEffectiveModuleResolution,
     buildImportMap,
     migrationCreatedBy,
     rewriteImports,
+    rewriteManifest,
     rewriteNames,
+    removeProjectKey,
     reportConstraints,
     patchAppModule,
     patchOptionsFor,
     planInit,
+    settingsWrittenTo,
+    findMovedSettings,
+    SCANNED_FOR_MOVED_SETTINGS,
+    WHERE_IT_GOES,
+    describeDbCatalogOccurrence,
+    findDbCatalogBlocks,
+    SCANNED_FOR_DB_CATALOG,
+    WHERE_DB_CATALOG_GOES,
 } from '../dist/index.js';
 
 const require_ = createRequire(import.meta.url);
@@ -68,7 +83,7 @@ const require_ = createRequire(import.meta.url);
 // `pascalCase` and came back as `value.replace is not a function` with exit 99
 // — an internal error for what is an ordinary typo.
 const VALUE_FLAGS = new Set([
-    'project-key',
+    'app-key',
     'app-name',
     'api-base',
     'quota',
@@ -132,14 +147,15 @@ async function selectFragmentFiles(dir, filter) {
 
 async function loadFragments(dir, filter) {
     const selected = await selectFragmentFiles(dir, filter);
-    const blocks = new Map();
+    const blocks = { enums: new Map(), models: new Map() };
     for (const file of selected) {
         const content = await readFile(join(dir, file), 'utf8');
-        const fileBlocks = extractModelBlocks(content);
-        for (const [name, body] of fileBlocks) {
-            if (!blocks.has(name)) {
-                blocks.set(name, body);
-            }
+        const fileBlocks = extractFragmentBlocks(content);
+        for (const [name, body] of fileBlocks.enums) {
+            if (!blocks.enums.has(name)) blocks.enums.set(name, body);
+        }
+        for (const [name, body] of fileBlocks.models) {
+            if (!blocks.models.has(name)) blocks.models.set(name, body);
         }
     }
     return { files: selected, blocks };
@@ -171,7 +187,7 @@ async function cmdSchemaApply(args) {
     }
 
     const { files, blocks } = await loadFragments(fragmentsDir, filter);
-    if (blocks.size === 0) {
+    if (blocks.models.size === 0) {
         console.error('✗ No models found in the selected fragments.');
         process.exit(1);
     }
@@ -185,13 +201,16 @@ async function cmdSchemaApply(args) {
     // one where the manual step is most likely to have been forgotten.
     const fk = resolveFkPointers(result.schema, args);
 
-    if (result.added.length === 0 && fk.enabled.length === 0) {
+    if (result.added.length === 0 && result.addedEnums.length === 0 && fk.enabled.length === 0) {
         console.log(`→ Nothing to do. Models already present: ${result.skipped.join(', ')}`);
         reportFkPointers(fk, args);
         return;
     }
 
     if (args['dry-run']) {
+        if (result.addedEnums.length) {
+            console.log(`(--dry-run) Would append enums: ${result.addedEnums.join(', ')}`);
+        }
         if (result.added.length) {
             console.log(`(--dry-run) Would append: ${result.added.join(', ')}`);
         }
@@ -209,12 +228,18 @@ async function cmdSchemaApply(args) {
         for (const { line } of fk.enabled) {
             console.log(`  ${line + 1}: ${fk.schema.split('\n')[line]?.trim() ?? ''}`);
         }
-        if (fk.enabled.length > 0 && result.added.length > 0) console.log('');
-        if (result.added.length > 0) console.log(result.schema.slice(schema.length));
+        const appended = result.added.length > 0 || result.addedEnums.length > 0;
+        if (fk.enabled.length > 0 && appended) console.log('');
+        if (appended) console.log(result.schema.slice(schema.length));
         return;
     }
 
     await writeFile(schemaPath, fk.schema, 'utf8');
+    if (result.addedEnums.length) {
+        console.log(
+            `✓ Appended ${result.addedEnums.length} enum(s): ${result.addedEnums.join(', ')}`,
+        );
+    }
     console.log(`✓ Appended ${result.added.length} model(s): ${result.added.join(', ')}`);
     if (result.skipped.length) {
         console.log(`→ Skipped (already present): ${result.skipped.join(', ')}`);
@@ -548,6 +573,7 @@ async function cmdCodemodV1Imports(args) {
     let rewritten = 0;
     let touched = 0;
     await walkSources(root, async (full, source) => {
+        if (basename(full) === CODEMOD_MANIFEST) return;
         const result = rewriteImports(source, map);
         for (const [subpath, n] of result.unmapped) {
             unmapped.set(subpath, (unmapped.get(subpath) ?? 0) + n);
@@ -592,8 +618,15 @@ async function cmdCodemodV1Rename(args) {
     const ambiguous = new Map();
     let rewritten = 0;
     let touched = 0;
+    let manifestsTouched = 0;
     await walkSources(root, async (full, source) => {
-        const result = rewriteNames(source, table);
+        // A manifest takes the package renames in its dependency fields; a
+        // source file takes everything. Under pnpm an import a manifest does
+        // not declare fails to resolve, so the two travel together.
+        const result =
+            basename(full) === CODEMOD_MANIFEST
+                ? rewriteManifest(source, table, { targetRange: `^${OWN_VERSION}` })
+                : rewriteNames(source, table);
         for (const name of result.ambiguous) {
             ambiguous.set(name, (ambiguous.get(name) ?? 0) + 1);
         }
@@ -601,11 +634,26 @@ async function cmdCodemodV1Rename(args) {
         if (!dryRun) await writeFile(full, result.text);
         rewritten += result.rewritten;
         touched += 1;
+        if (basename(full) === CODEMOD_MANIFEST) manifestsTouched += 1;
     });
 
     console.log(
         `${dryRun ? 'Would rewrite' : 'Rewrote'} ${rewritten} name(s) in ${touched} file(s).`,
     );
+    if (manifestsTouched > 0) {
+        // The lockfile is not rewritten: its shape is the package manager's,
+        // and a wrong guess at it is worse than an honest instruction. A CI
+        // that installs with a frozen lockfile refuses the migrated checkout
+        // until it is regenerated.
+        console.log('');
+        console.log(
+            `${manifestsTouched} package.json ${manifestsTouched === 1 ? 'file' : 'files'} changed — ` +
+                'regenerate the lockfile before committing:',
+        );
+        console.log(
+            '  pnpm install   (or npm install / yarn install, whichever owns your lockfile)',
+        );
+    }
     if (ambiguous.size === 0) return;
 
     console.log('');
@@ -617,8 +665,20 @@ async function cmdCodemodV1Rename(args) {
     console.log('  FEATURE_UI_REGISTRY_TOKEN meant one registry in `@saasicat/nest/billing`');
     console.log('  and another in `@saasicat/nest/catalog`. Import it from the entry you');
     console.log('  mean — BILLING_FEATURE_UI_REGISTRY_TOKEN or CATALOG_FEATURE_UI_REGISTRY_TOKEN.');
+    console.log('  A dependency listed "in <field> (<range>)" points at a workspace or a path;');
+    console.log('  rename it by hand to @saasicat/core at the location you keep it.');
 }
 
+/**
+ * The version this CLI was released as — and therefore the line a consumer
+ * running its codemod is migrating to. The manifest rewrite sets the renamed
+ * dependency to `^<this>`, because the old range (`^0.27.0`) names a line
+ * the renamed package was never published on.
+ */
+const OWN_VERSION = JSON.parse(
+    await readFile(join(dirname(require_.resolve('@saasicat/cli')), '..', 'package.json'), 'utf8'),
+).version;
+
 /** Where a shipped codemod table lives, resolved through the package itself. */
 function codemodTable(name) {
     return join(dirname(require_.resolve('@saasicat/cli')), '..', 'codemods', name);
@@ -630,9 +690,32 @@ function codemodTable(name) {
 const CODEMOD_SKIP = new Set(['node_modules', '.git', '.output', 'coverage']);
 const isBuildOutput = (name) => name === 'dist' || name.startsWith('dist-');
 const CODEMOD_EXTENSIONS = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|vue|md)$/;
+/**
+ * Widens the walk for `v1-project-key` alone — see `walkSources`.
+ *
+ * `.prisma` belongs here for the reason `.yaml` does: a consumer copies the
+ * platform's models into their own `schema.prisma`, which is the documented
+ * integration path, so that file carries `projectKey` fields and composite
+ * indexes of its own. Left out of the walk they were neither rewritten nor
+ * reported — and after the SQL migration drops the columns, a schema still
+ * declaring them generates a client that queries them, while the next
+ * `db push` tries to put them back.
+ *
+ * Reported rather than rewritten, like every other declaration: a `.prisma`
+ * model is a schema, and which of its fields a consumer still needs is theirs.
+ */
+const CODEMOD_CONFIG_EXTENSIONS = /\.(yaml|yml|prisma)$/;
+/** Walked for the package renames alone; see `rewriteManifest`. */
+const CODEMOD_MANIFEST = 'package.json';
 
-/** Every source file under `root` a codemod may touch, with its text. */
-async function walkSources(root, visit) {
+/**
+ * Every source file under `root` a codemod may touch, with its text.
+ *
+ * `extra` widens the set for one codemod. Only `v1-project-key` passes it, and
+ * only for `.yaml`: the other two rewrite identifiers and import specifiers,
+ * and letting them loose on a configuration file would corrupt it.
+ */
+async function walkSources(root, visit, extra = null) {
     const walk = async (dir) => {
         for (const entry of await readdir(dir, { withFileTypes: true })) {
             if (CODEMOD_SKIP.has(entry.name) || isBuildOutput(entry.name)) continue;
@@ -641,13 +724,151 @@ async function walkSources(root, visit) {
                 await walk(full);
                 continue;
             }
-            if (!CODEMOD_EXTENSIONS.test(entry.name)) continue;
+            const included =
+                CODEMOD_EXTENSIONS.test(entry.name) ||
+                entry.name === CODEMOD_MANIFEST ||
+                (extra !== null && extra.test(entry.name));
+            if (!included) continue;
             await visit(full, await readFile(full, 'utf8'));
         }
     };
     await walk(root);
 }
 
+/**
+ * Takes `projectKey` out of a consumer's code, and names what it will not.
+ *
+ * A removal is not a rename: the word is an ordinary property name. Two forms
+ * need no grammar to decide — a `?projectKey=` on a `/catalog/` URL, and the
+ * top-level key of a `saas.yaml` — and those are rewritten. An object member is
+ * reported: an object literal and a type literal are lexically identical in
+ * TypeScript, so removing one would sometimes delete a member of the consumer's
+ * own type. The migration guide's table says what each shape becomes.
+ */
+/**
+ * Names the module options that moved into `config/saas.yaml`.
+ *
+ * Read-only on purpose — see `codemods/v1-moved-settings.ts` for why removing
+ * them would lose the decision instead of moving it. `--dry-run` is accepted
+ * and does nothing, so `codemod v1 --dry-run` behaves the same throughout.
+ */
+async function cmdCodemodV1MovedSettings(args) {
+    const root = resolve(args.dir ?? '.');
+    const found = [];
+    const blocks = [];
+
+    await walkSources(root, async (full, source) => {
+        // Code only. The walk includes Markdown, and a documentation file that
+        // mentions a setting is not a file that passes one — see
+        // `SCANNED_FOR_MOVED_SETTINGS`.
+        if (!SCANNED_FOR_MOVED_SETTINGS.test(full)) return;
+        for (const { setting, line } of findMovedSettings(source).occurrences) {
+            found.push({ where: `${relative(root, full)}:${line}`, setting });
+        }
+        if (!SCANNED_FOR_DB_CATALOG.test(full)) return;
+        for (const { shape, line, leftovers } of findDbCatalogBlocks(source).occurrences) {
+            blocks.push({ where: `${relative(root, full)}:${line}`, shape, leftovers });
+        }
+    });
+
+    if (found.length === 0) {
+        console.log('No module option that moved into config/saas.yaml is still passed.');
+        reportDbCatalogBlocks(blocks);
+        return;
+    }
+
+    console.log(`${found.length} occurrence(s) of a setting that moved:`);
+    const width = Math.max(...found.map((f) => f.where.length));
+    for (const { where, setting } of found) {
+        console.log(`  ${where.padEnd(width)}  ${setting}`);
+    }
+    console.log('');
+    console.log('  Not removed, and that is the point: the value is a term somebody agreed,');
+    console.log('  and deleting it here without writing it into the file would leave the');
+    console.log('  application running on whatever the file happens to say. Move each one:');
+    console.log('');
+    for (const setting of new Set(found.map((f) => f.setting))) {
+        console.log(`  ${setting}`);
+        console.log(`      ${WHERE_IT_GOES[setting]}`);
+    }
+    console.log('');
+    console.log('  TenantBillingModule.forRoot() refuses to boot while either is still');
+    console.log('  passed, so this cannot be half-done quietly.');
+    console.log('');
+    reportDbCatalogBlocks(blocks);
+}
+
+/**
+ * Names a `dbCatalog` that still carries the settings as values.
+ *
+ * The same decision as the settings above, one option up: the values were
+ * forwarded from `config/saas.yaml`, and the option names that file now. Not
+ * rewritten, because which file is a variable in another module more often
+ * than a literal here — see `codemods/v1-db-catalog.ts`.
+ */
+function reportDbCatalogBlocks(blocks) {
+    if (blocks.length === 0) {
+        console.log('No dbCatalog still carries the settings as values.');
+        return;
+    }
+    console.log(`${blocks.length} dbCatalog block(s) to point at the file:`);
+    const width = Math.max(...blocks.map((b) => b.where.length));
+    for (const { where, shape, leftovers } of blocks) {
+        console.log(
+            `  ${where.padEnd(width)}  ${describeDbCatalogOccurrence({ shape, leftovers })}`,
+        );
+    }
+    console.log('');
+    console.log(`  ${WHERE_DB_CATALOG_GOES}`);
+    console.log('');
+    console.log('  SaaSiCatModule.forRoot() refuses to boot while the values are still passed,');
+    console.log('  so this cannot be half-done quietly.');
+    console.log('');
+}
+
+async function cmdCodemodV1ProjectKey(args) {
+    const root = resolve(args.dir ?? '.');
+    const dryRun = args['dry-run'] === true;
+
+    const undecided = [];
+    let rewritten = 0;
+    let touched = 0;
+    await walkSources(
+        root,
+        async (full, source) => {
+            if (basename(full) === CODEMOD_MANIFEST) return;
+            const result = removeProjectKey(source, isCatalogConfig(full) ? 'yaml' : 'source');
+            for (const line of result.undecided) undecided.push(`${relative(root, full)}:${line}`);
+            if (result.rewritten === 0) return;
+            if (!dryRun) await writeFile(full, result.text);
+            rewritten += result.rewritten;
+            touched += 1;
+        },
+        CODEMOD_CONFIG_EXTENSIONS,
+    );
+
+    console.log(
+        `${dryRun ? 'Would remove' : 'Removed'} ${rewritten} occurrence(s) in ${touched} file(s).`,
+    );
+    if (undecided.length === 0) return;
+
+    console.log('');
+    console.log(`${undecided.length} occurrence(s) are yours to look at:`);
+    for (const where of undecided) console.log(`  ${where}`);
+    console.log('');
+    console.log('  Two kinds of file end up here. In TypeScript an object literal and a type');
+    console.log('  literal are the same tokens, so this cannot tell a payload member from one');
+    console.log('  of your own declarations without parsing. And a `.prisma` model is a schema:');
+    console.log("  which of its fields you still need is yours to say, not this tool's.");
+    console.log('  It reports rather than guesses — docs/guides/upgrade-to-1.0.md has a table');
+    console.log('  of what each shape becomes.');
+}
+
+/** A `saas.yaml`, whose top-level `projectKey:` needs no anchor. */
+function isCatalogConfig(full) {
+    return basename(full) === 'saas.yaml' || basename(full) === 'saas.yml';
+}
+
 /** Reads a repeated flag (`--quota=a --quota=b`) off argv. */
 function repeatedFlag(argv, name) {
     return argv
@@ -656,25 +877,42 @@ function repeatedFlag(argv, name) {
 }
 
 async function cmdInit(args, argv) {
-    if (!args['project-key']) {
-        console.error('✗ --project-key=<key> is required.');
-        console.error('  It names the catalogue this app administers.');
+    if (!args['app-key']) {
+        console.error('✗ --app-key=<key> is required.');
+        console.error('  It is the slug of this application: npm package name, storage prefix.');
         process.exit(1);
     }
 
     // A usage error, so it exits 1 like every other one here rather than
-    // through the top-level handler's 99. The rule itself comes from the
-    // catalogue schema — see src/init/project-key.ts.
+    // through the top-level handler's 99. The rule itself is in
+    // src/init/catalog-keys.ts.
     try {
-        assertValidProjectKey(args['project-key']);
+        assertValidAppKey(args['app-key']);
     } catch (err) {
         console.error(`✗ ${err.message}`);
         process.exit(1);
     }
 
     const root = resolve(args.dir ?? '.');
+
+    // Before anything is written: the files below import subpath exports,
+    // and under `moduleResolution: node` none of them resolves. Found by
+    // running the quickstart against an app that predates `nodenext`.
+    if (existsSync(join(root, 'tsconfig.json'))) {
+        const ts = loadTypeScript(root);
+        if (ts === null) {
+            console.log('! tsconfig.json not checked: no TypeScript resolvable from this project.');
+        } else {
+            const verdict = judgeModuleResolution(readEffectiveModuleResolution(root, ts));
+            if (!verdict.ok) {
+                console.error(`✗ ${verdict.reason}`);
+                process.exit(1);
+            }
+        }
+    }
+
     const plan = planInit({
-        projectKey: args['project-key'],
+        appKey: args['app-key'],
         appName: args['app-name'],
         apiBase: args['api-base'],
         quotas: repeatedFlag(argv, 'quota'),
@@ -726,6 +964,8 @@ async function cmdInit(args, argv) {
         for (const w of writes) console.log(`    ${w.path}`);
     }
 
+    reportSettings(writes, root);
+
     await patchAppModuleFile(root, plan, args);
 
     console.log('');
@@ -734,14 +974,62 @@ async function cmdInit(args, argv) {
     console.log('     — the generated app does NOT compile until you do. An empty');
     console.log('       array means "deliberately auth-free" to the platform, and');
     console.log('       would publish GET /admin/discovery to anyone who asks.');
+    console.log('  2. Name the modules in `imports: [YourPrismaModule, YourAuthModule]`');
+    console.log('     — the one exporting PrismaService and the one your guard needs.');
+    console.log('       The platform module resolves its providers from that list;');
+    console.log('       without it the first boot stops at "Nest can\'t resolve');
+    console.log('       dependencies of … (PrismaService)".');
     if (plan.quotaProviders.length > 0) {
-        console.log('  2. Check each quota provider counts the right thing');
-        console.log('  3. saasicat schema migrate --name=add_saasicat');
+        console.log('  3. Check each quota provider counts the right thing');
+        console.log('  4. saasicat schema migrate --name=add_saasicat');
     } else {
-        console.log('  2. saasicat schema migrate --name=add_saasicat');
+        console.log('  3. saasicat schema migrate --name=add_saasicat');
     }
 }
 
+/**
+ * Says which settings the catalogue now carries, with their values and its path.
+ *
+ * These are required fields without defaults, and there is no second place they
+ * can come from. Somebody who has just run `init` should not have to find that
+ * out from a boot failure six weeks later — so the command names the file it
+ * put them in while they are still looking at the output.
+ *
+ * Derived in `init/settings-written.ts`, where it can be tested: this file is
+ * not.
+ */
+function reportSettings(writes, root) {
+    const catalog = writes.find((w) => w.path === 'config/saas.yaml');
+    if (!catalog) return;
+    const settings = settingsWrittenTo(catalog.content, catalog.path);
+    if (settings.length === 0) return;
+
+    const width = Math.max(...settings.map((s) => s.key.length));
+    console.log('');
+    console.log(`Settings written to ${join(root, catalog.path)}:`);
+    for (const { key, value } of settings) {
+        console.log(`    ${key.padEnd(width)}  ${value}`);
+    }
+    console.log('  This file is where they live. Editing it is how they change, and the');
+    console.log('  change lands on the next restart — the platform reads it at boot.');
+}
+
+/**
+ * The TypeScript that will compile the project: the consumer's own, resolved
+ * from the project root, so the tsconfig is read the way the build reads it.
+ * Falls back to the one this CLI was installed with, then to null.
+ */
+function loadTypeScript(root) {
+    for (const from of [join(root, 'package.json'), import.meta.url]) {
+        try {
+            return createRequire(from)('typescript');
+        } catch {
+            // Not resolvable from here — try the next origin.
+        }
+    }
+    return null;
+}
+
 /** Adds the platform to `src/app.module.ts`, or says exactly what to paste. */
 async function patchAppModuleFile(root, plan, args) {
     const appModulePath = join(root, 'src', 'app.module.ts');
@@ -793,11 +1081,19 @@ async function main() {
     if (cmd === 'codemod' && sub === 'v1-rename') {
         return cmdCodemodV1Rename(parseArgs(rest));
     }
+    if (cmd === 'codemod' && sub === 'v1-project-key') {
+        return cmdCodemodV1ProjectKey(parseArgs(rest));
+    }
+    if (cmd === 'codemod' && sub === 'v1-moved-settings') {
+        return cmdCodemodV1MovedSettings(parseArgs(rest));
+    }
     if (cmd === 'codemod' && sub === 'v1') {
         // Imports first: the rename table keys its per-entry tokens by the
         // specifier they are imported from, which the import rewrite settles.
         await cmdCodemodV1Imports(parseArgs(rest));
-        return cmdCodemodV1Rename(parseArgs(rest));
+        await cmdCodemodV1Rename(parseArgs(rest));
+        await cmdCodemodV1ProjectKey(parseArgs(rest));
+        return cmdCodemodV1MovedSettings(parseArgs(rest));
     }
     if (cmd === 'init') {
         return cmdInit(parseArgs([sub, ...rest].filter(Boolean)), process.argv.slice(3));
@@ -826,18 +1122,23 @@ async function main() {
             '  schema migrate --name=<name>             apply --all + migrate dev + constraints',
         );
         console.log('');
-        console.log('  init --project-key=<key> --quota=<key>:<Model>');
+        console.log('  init --app-key=<key> --quota=<key>:<Model>');
         console.log('          scaffold the platform wiring. At least one --quota:');
         console.log('          every plan must declare one, or the catalogue does not load.');
-        console.log('  init --project-key=myapp --quota=notes:Note --quota=seats:Seat');
+        console.log('  init --app-key=myapp --quota=notes:Note --quota=seats:Seat');
         console.log('');
         console.log('  codemod v1 [--dir=.] [--dry-run]');
-        console.log('          the whole 1.0 migration: v1-imports, then v1-rename');
+        console.log('          the whole 1.0 migration: imports, names, projectKey, then the');
+        console.log('          settings that moved into config/saas.yaml');
         console.log('  codemod v1-imports [--dir=.] [--dry-run]');
         console.log('          rewrite @saasicat/ui-vue imports to the 1.0 export map');
         console.log('  codemod v1-rename [--dir=.] [--dry-run]');
         console.log('          rewrite the names 1.0 changed: SaasPlatform*, Symbol.for keys,');
         console.log('          FEATURE_UI_REGISTRY_TOKEN, @saasicat/ui-vue/testing-e2e/*');
+        console.log('  codemod v1-moved-settings [--dir=.]');
+        console.log('          name the module options that moved into config/saas.yaml.');
+        console.log('          Reports only — the value is a commercial decision, and this');
+        console.log('          would delete it without writing it anywhere.');
         console.log('');
         console.log('Optional --prisma-schema=PATH (default prisma/schema.prisma).');
         console.log('Optional --tenant-model=X --user-model=Y for apply/migrate — enables');

package/codemods/v1-rename.map.json

@@ -15,6 +15,8 @@
         "consumer that spelled a key themselves gets the same symbol the platform",
         "now registers; without this their injection would resolve to nothing.",
         "",
+        "`packages` renames a whole package — in specifiers and in package.json.",
+        "",
         "`entryTokens` is keyed by the import specifier, because the old name",
         "meant different registries in different entries. An import of it from",
         "anywhere else is reported, not guessed."
@@ -41,5 +43,9 @@
     },
     "subpaths": {
         "@saasicat/ui-vue/testing-e2e/": "@saasicat/ui-vue/testing/"
+    },
+    "packages": {
+        "_": "A package that was renamed. Applied to import specifiers AND to the dependency fields of every package.json the walk meets: an import rewritten without its manifest does not resolve under pnpm.",
+        "@saasicat/types": "@saasicat/core"
     }
 }

package/dist/.build-stamp

@@ -1 +1 @@
-87fdb737df2d686fe3d296add0d87c2a3765371380b486e2ff20fda896b3db65
+83558356586a974819603d3c58eb8044516515cce6507e6156db23e7a89b1aac