@saasicat/cli 1.0.0-rc.2 → 1.0.0-rc.20

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 { basename, 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';
@@ -46,7 +49,7 @@ import {
     extractFragmentBlocks,
     findFkPointers,
     hasConstraints,
-    assertValidProjectKey,
+    assertValidAppKey,
     judgeModuleResolution,
     readEffectiveModuleResolution,
     buildImportMap,
@@ -54,10 +57,19 @@ import {
     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);
@@ -71,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',
@@ -278,6 +290,16 @@ function printCheckReport(report) {
         console.log('');
     }
 
+    if (report.tenantCascades.length > 0) {
+        console.log(`✗ Deleted together with the tenant (${report.tenantCascades.length}):`);
+        for (const { model, field } of report.tenantCascades) {
+            console.log(`    ${`${model}.${field}`.padEnd(44)} onDelete: Cascade`);
+        }
+        console.log('  These records outlive their tenant — a contract is kept for tax purposes.');
+        console.log('  Remove the relation; `tenantId` stays as a trace.');
+        console.log('');
+    }
+
     const breaking = report.missingBlockAttributes.filter((a) => a.kind !== 'index');
     if (breaking.length > 0) {
         console.log(`✗ Missing constraints (${breaking.length}):`);
@@ -298,7 +320,16 @@ function printCheckReport(report) {
         console.log('');
     }
 
-    const absent = [...report.absentModels, ...report.absentEnums];
+    // An enum a reported field names is not a fragment the app went without: the
+    // field above it is the drift, and copying the enum is what fixes both.
+    // Listing it as "not an error" in the same run would print the contradiction
+    // this check exists to avoid — which is exactly what it used to do for a
+    // relation pointing at an unadopted model.
+    const named = new Set(report.missingFields.map((field) => field.type));
+    const absent = [
+        ...report.absentModels,
+        ...report.absentEnums.filter((name) => !named.has(name)),
+    ];
     if (absent.length > 0) {
         console.log(`→ Not adopted (${absent.length}): ${absent.join(', ')}`);
         console.log('  Not an error — the app does not use these fragments.');
@@ -325,7 +356,21 @@ async function cmdSchemaCheck(args) {
     console.log(`→ Checking ${schemaPath} against ${files.length} fragment(s) from @saasicat/spec`);
     console.log('');
 
-    const report = checkSchema(fragments.join('\n'), schema);
+    // Every model the shipped fragments declare, not only the selected ones: a
+    // relation from a selected fragment can point at a model in one that was
+    // left out, and without this the narrowed run would report that field as
+    // missing — the very contradiction the full run stopped producing. Without
+    // a filter the files in hand are already all of them.
+    const allFragments = filter
+        ? await Promise.all(
+              (await selectFragmentFiles(fragmentsDir, null)).map((file) =>
+                  readFile(join(fragmentsDir, file), 'utf8'),
+              ),
+          )
+        : fragments;
+    const knownModels = new Set(extractModelNames(allFragments.join('\n')));
+
+    const report = checkSchema(fragments.join('\n'), schema, knownModels);
     printCheckReport(report);
 
     const checked = `${report.checkedModelCount} Model(s), ${report.checkedEnumCount} Enum(s)`;
@@ -678,11 +723,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;
@@ -691,13 +757,151 @@ async function walkSources(root, visit) {
                 await walk(full);
                 continue;
             }
-            if (!CODEMOD_EXTENSIONS.test(entry.name) && entry.name !== CODEMOD_MANIFEST) 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
@@ -706,17 +910,17 @@ 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);
@@ -741,7 +945,7 @@ async function cmdInit(args, argv) {
     }
 
     const plan = planInit({
-        projectKey: args['project-key'],
+        appKey: args['app-key'],
         appName: args['app-name'],
         apiBase: args['api-base'],
         quotas: repeatedFlag(argv, 'quota'),
@@ -793,6 +997,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('');
@@ -814,6 +1020,33 @@ async function cmdInit(args, argv) {
     }
 }
 
+/**
+ * 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.
@@ -881,11 +1114,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));
@@ -914,18 +1155,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/dist/.build-stamp

@@ -1 +1 @@
-d16106f714ce74c061cc0211a2be4ebe01a1cb80b8e4b5da45ff296c861cff71
+89cdc61db4ad8f0d8bc18287c0d1fe76e1a7e9410f0797a525db4c9b1bbdc3ab