@niscorp/cli 0.8.2 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,34 @@
1
1
  # @niscorp/cli
2
2
 
3
+ ## 0.9.1
4
+
5
+ ### Patch Changes
6
+
7
+ - a7b2a05: A shape check, `runShapeCheck` from the new entry `@niscorp/cli/shape`: it reads an app's source and its actions for what its own checks cannot see — rule 16 by the TypeScript compiler, formatting outside Prism, roles read in server code, the kit reading files, the address or the document, code in `src/app` called while the app runs — and fails on every server function an action calls that the app has not named with why it is not a vex read or write. What an app allows, it names per rule and per file, each with its reason. It reads with the app's own TypeScript (6.x) and adds no dependency.
8
+
9
+ `create-nisc` writes it into every app as `src/dev/shape-check.ts`, run by `npm run check`. The rulebook's "Verification" and `REVIEW.md` say what it does.
10
+
11
+ **What to change:** nothing; an app that does not call it is not checked. To check an app made before this, copy `src/dev/shape-check.ts` from a new one, add it to `src/dev/all-checks.ts`, and name what it reports.
12
+
13
+ ## 0.9.0
14
+
15
+ ### Minor Changes
16
+
17
+ - 2780c56: A real database's tables change only through `nisc migrate`. `migrations` on the runtime defaults to `'verify'`: `createServer` — and so `nisc dev`, `nisc build` and `nisc start` — checks the tables and refuses to start while a migration is pending, naming each one and the two commands that apply it (`npx nisc migrate --check`, then `npx nisc migrate`). On a database that is up to date the check only reads the ledger, so the app's database role needs `SELECT` on `strata_ledger` and no right to change tables. A runtime whose database starts empty every time (PGlite in memory) writes `migrations: 'apply'` and is migrated at boot as before.
18
+
19
+ The boot and `migrateTables` refuse a database whose ledger records a sequence they do not name (`UNKNOWN_SEQUENCE`): a sequence that has run stays in `runtime.tables`.
20
+
21
+ `migrateTables` and `nisc migrate` refuse a run that removes a table or a column, or changes a column's type, unless `allowRemoval` / `--allow-removal` is given; the refusal names each. A run that applied nothing, because another run had already applied it, is not refused.
22
+
23
+ `tableStatus(runtime, app)` and `nisc migrate --status`: what is applied and what is pending, read and nothing else.
24
+
25
+ BREAKING — approved by moccadroid, 2026-11-07: a runtime on a real database runs `nisc migrate` before the app starts (on Railway, the service's pre-deploy command `pnpm exec nisc migrate`); a runtime on in-memory PGlite writes `migrations: 'apply'`; every sequence that has run on the database is in `runtime.tables` (`TIDE_SEQUENCE` with the store made `migrate: false`), and the runtime migrates nothing itself and calls no `cache.init()`; a database that has not yet run `nisc.moss/4` is migrated once with `--allow-removal`.
26
+
27
+ ### Patch Changes
28
+
29
+ - Updated dependencies [2780c56]
30
+ - @niscorp/moss@0.9.0
31
+
3
32
  ## 0.8.2
4
33
 
5
34
  ### Patch Changes
package/README.md CHANGED
@@ -15,7 +15,7 @@ nisc build # bundle the app, draw every path, and check what was drawn
15
15
  nisc export # build, then write every path as a file — the site as a folder
16
16
  nisc start # serve the built app, each path's first screen drawn
17
17
  nisc check # the app's check suite
18
- nisc migrate # apply the tables' pending migrations, if the app's entries fit the result
18
+ nisc migrate # apply the tables' pending migrations, if the app's entries fit the result — the only command that changes a real database
19
19
  ```
20
20
 
21
21
  An app is one of two things, and the command runs both. **Behind moss**, the
@@ -347,11 +347,75 @@ server. An app with its own shell is a vite app and nothing more.
347
347
  The app's check suite (`src/dev/all-checks.ts`, or `checks` in the config), run
348
348
  with the app's own `tsx`. Its exit code is the suite's.
349
349
 
350
+ ## The shape check — `@niscorp/cli/shape`
351
+
352
+ An app's own checks test what it does. The shape check reads how it does it:
353
+ its source and its actions, for what nisc's rulebook (`AGENTS.md` in
354
+ `@niscorp/nisc`) says an app is made of. An app runs it from its suite, as
355
+ `src/dev/shape-check.ts`; `npm create nisc` writes that file. An app that does
356
+ not call it is not checked.
357
+
358
+ ```ts
359
+ import { fileURLToPath } from 'node:url';
360
+ import { runShapeCheck } from '@niscorp/cli/shape';
361
+ import { actions } from '../app/action-catalog';
362
+ import { ENTRIES } from '../app/vex';
363
+
364
+ process.exit(
365
+ runShapeCheck({
366
+ root: fileURLToPath(new URL('../..', import.meta.url)),
367
+ actions: Object.values(actions),
368
+ entries: ENTRIES,
369
+ functions: { ask: 'the model composes the answer to a message' },
370
+ allow: { formatting: { 'src/server/today.ts': 'the studio’s day, put in every read’s scope' } },
371
+ }),
372
+ );
373
+ ```
374
+
375
+ It prints one `[pass]` or `[fail]` line per rule and answers the exit code, 0
376
+ or 1. It fails when:
377
+
378
+ | Rule | It fails on |
379
+ |---|---|
380
+ | `style` (rule 16) | in `src/`: an `as` or `<T>` assertion other than `as const`, a non-null `!`, a `function` declaration, a class, an enum, `any`, a default export. `.d.ts` files are not read |
381
+ | `formatting` (rule 9) | `Intl.` or a `.toLocale…()` call in `src/`, but `src/dev/` |
382
+ | `roles` (rule 11) | `session.roles` or `principal.roles` in `src/server/` |
383
+ | `files` (rule 9a) | `FileReader` or a `readAs…` call in `src/ui/` |
384
+ | `address` (rule 4) | `location.…`, `history.pushState` or `history.replaceState` in `src/ui/` |
385
+ | `dom` (rule 2) | `document.querySelector` and its kin in `src/ui/` |
386
+ | `data` | a file in `src/` outside `src/app/` and `src/dev/` imports a function from `src/app/` — resolved by the app's `tsconfig.json`, so a path alias counts. A function that answers the manifest (`NiscApp`) is setup, and passes |
387
+
388
+ Each is read off the syntax tree, so a word in a comment or a string is never a
389
+ finding.
390
+
391
+ `allow` names, per rule, the files that may do what the rule refuses, each with
392
+ why: the file that finds the app's day, the identity seam that reads roles, a
393
+ routing adapter, a shim. An allowance fails when it gives no reason, names a
394
+ file that is not there, or allows nothing in that file.
395
+
396
+ `functions` names every server function an action calls (an endpoint with
397
+ `fn`), each with what it does that a vex read or write replayed by the action
398
+ cannot: mail, a model, files, what lives in the person's shell. A function an
399
+ action calls that is not named fails, and so does a name no action calls.
400
+
401
+ It also prints, failing on nothing, how often the actions call functions
402
+ against how often they replay vex, how many reads word their rows with a Prism
403
+ `mapping`, and the `refresh: 'reactive'` reads no action replays by name.
404
+
405
+ It reads the source with the app's own TypeScript, 6.x, found from `root`, and
406
+ the app as its `tsconfig.json` there says. On lyceum it takes under three
407
+ seconds.
408
+
350
409
  ## `nisc migrate`
351
410
 
352
411
  For an app behind moss whose config hands over `app` and `runtime`. It is the
353
- step a deployment runs before the new version starts, when its runtime says
354
- `migrations: 'verify'`.
412
+ only command that changes a real database's tables: `nisc dev`, `nisc build`
413
+ and `nisc start` boot the app, and a boot only checks the tables — with a
414
+ migration pending it refuses to start and names it — unless the runtime says
415
+ `migrations: 'apply'`, which a database that starts empty every time (PGlite in
416
+ memory) does. A deployment runs it before the new version starts; on Railway,
417
+ as the service's pre-deploy command (`pnpm exec nisc migrate`): a failure stops
418
+ the deploy, and the running version keeps serving.
355
419
 
356
420
  In one transaction it applies every pending table migration — moss's, and the
357
421
  app's own (`runtime.tables`) — then checks that every entry of the manifest
@@ -366,19 +430,39 @@ nisc: applied 1
366
430
  nisc: this run removes notes.stars
367
431
  ```
368
432
 
369
- A run that lands says what it took away (tables and columns removed, column
370
- types changed). An entry that already did not fit before the run, and is
371
- already seeded as it is, is listed and does not refuse the run.
433
+ A run that takes something away — a table or a column removed, a column's
434
+ type changed — is refused, each named, unless `--allow-removal` is given; then
435
+ it lands and says what it took away. It sees tables and columns, not rows a
436
+ step deletes. An entry that already did not fit before the run, and is already
437
+ seeded as it is, is listed and does not refuse the run.
372
438
 
373
439
  `--check` does all of it and rolls it back. It takes the locks the real run
374
440
  will take, for as long.
375
441
 
442
+ `--status` reads and changes nothing: how many migrations of each sequence the
443
+ database records and what is pending (exit 0), and anything that would refuse
444
+ a run — an edited migration, a database migrated by newer code, a sequence
445
+ nobody names (exit 1).
446
+
447
+ ```
448
+ nisc: applied nisc.moss 6, nisc.moss.sessions 1, nisc.vex.cache 2, acme.app 2
449
+ nisc: 1 pending
450
+ acme.app/3 notes lose their stars
451
+ ```
452
+
453
+ A run waits for another one running at the same time, up to an hour, and a
454
+ step that waits more than 10 s for a table another query holds gives up — the
455
+ run is rolled back, and running it again is safe.
456
+
376
457
  `runtime` only opens the environment. It migrates nothing and seeds nothing:
377
458
  tables it changes itself are changed before the step can check them, and
378
- `--check` would then change the database. Every table an entry reads or writes
379
- comes from a sequence in the run — the app's own go in `runtime.tables`, and so
380
- does tide's (`TIDE_SEQUENCE`, from `@niscorp/tide/postgres`) when the app keeps
381
- tide's tables.
459
+ `--check` would then change the database. So it calls no `cache.init()` (the
460
+ server does, after its check), and a tide store under moss is made
461
+ `migrate: false`. Every table an entry reads or writes comes from a sequence in
462
+ the run — the app's own go in `runtime.tables`, and so does tide's
463
+ (`TIDE_SEQUENCE`, from `@niscorp/tide/postgres`) when the app keeps tide's
464
+ tables. A sequence that has run stays there: the run refuses a database that
465
+ records one nobody names.
382
466
 
383
467
  It checks entries. It does not see SQL written by hand, and it does not know
384
468
  what a value means.
@@ -392,6 +476,8 @@ what a value means.
392
476
  | `--allow-live` | `export`: write even though some path wants a server |
393
477
  | `--skip-bundle` | `build`, `export`: the terminal is already built — it is neither bundled nor has its stylesheet written into its page |
394
478
  | `--check` | `migrate`: do all of it, then roll it back |
479
+ | `--status` | `migrate`: what is applied and pending — reads, changes nothing |
480
+ | `--allow-removal` | `migrate`: apply a run that removes a table or column, or changes a column's type |
395
481
  | `--port <n>` | `dev`, `start`: the port (`start`: `$PORT`, then 8787) |
396
482
 
397
483
  ## License
package/dist/cli.js CHANGED
@@ -627,12 +627,23 @@ var migrate = async (options) => {
627
627
  if (isShellProject(project) || project.app === void 0 || project.runtime === void 0) {
628
628
  throw new Error("nisc: `nisc migrate` needs `app` and `runtime` in nisc.config.ts \u2014 the manifest, and the environment it runs on.");
629
629
  }
630
- const { migrateTables } = await import('@niscorp/moss');
630
+ const { migrateTables, tableStatus } = await import('@niscorp/moss');
631
631
  const print = say(options);
632
632
  const isDryRun = options.dryRun === true;
633
633
  const runtime = await project.runtime();
634
634
  try {
635
- const report = await migrateTables(runtime, project.app, isDryRun ? { dryRun: true } : {});
635
+ if (options.status === true) {
636
+ const plan = await tableStatus(runtime, project.app);
637
+ print(`nisc: applied ${Object.entries(plan.applied).map(([sequence, n]) => `${sequence} ${n}`).join(", ")}`);
638
+ print(plan.pending.length === 0 ? "nisc: nothing pending" : `nisc: ${plan.pending.length} pending`);
639
+ for (const migration of plan.pending) print(` ${migration.ref} ${migration.description}`);
640
+ if (plan.problems.length > 0) {
641
+ const problems = plan.problems.map((problem) => ` ${problem.code}: ${problem.detail}`);
642
+ throw new Error(["nisc: this database cannot be migrated or booted as it is:", ...problems].join("\n"));
643
+ }
644
+ return;
645
+ }
646
+ const report = await migrateTables(runtime, project.app, { ...isDryRun ? { dryRun: true } : {}, ...options.allowRemoval === true ? { allowRemoval: true } : {} });
636
647
  if (report.applied.length === 0) print("nisc: nothing to migrate");
637
648
  else print(isDryRun ? `nisc: would apply ${report.applied.length} \u2014 rolled back, nothing changed` : `nisc: applied ${report.applied.length}`);
638
649
  for (const migration of report.applied) print(` ${migration.ref} ${migration.description}`);
@@ -663,6 +674,7 @@ var USAGE = `nisc \u2014 the command for a nisc application
663
674
  nisc start serve the built app, each path's first screen drawn
664
675
  nisc check the app's check suite
665
676
  nisc migrate apply the tables' pending migrations, if the app's entries fit the result
677
+ (the only command that changes a real database's tables; boot only checks them)
666
678
 
667
679
  --root <dir> the app's root (default: here) \u2014 where nisc.config.ts is
668
680
  --out <dir> export: where the files go (default: out)
@@ -670,6 +682,8 @@ var USAGE = `nisc \u2014 the command for a nisc application
670
682
  --port <n> dev, start: the port (start: $PORT, then 8787)
671
683
  --skip-bundle build, export: the terminal is already built
672
684
  --check migrate: do all of it, then roll it back
685
+ --status migrate: what is applied and what is pending \u2014 reads, changes nothing
686
+ --allow-removal migrate: apply a run that removes a table or column or changes a column's type
673
687
 
674
688
  An app says in nisc.config.ts how it boots and how one of its screens is drawn.
675
689
  Behind moss (boot + draw): which paths exist and what each needs is read off the
@@ -701,7 +715,7 @@ var main = async () => {
701
715
  }
702
716
  if (command === "check") return check(options);
703
717
  if (command === "migrate") {
704
- await migrate({ ...options, dryRun: args.includes("--check") });
718
+ await migrate({ ...options, dryRun: args.includes("--check"), status: args.includes("--status"), allowRemoval: args.includes("--allow-removal") });
705
719
  return 0;
706
720
  }
707
721
  if (command === "build") {