@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 +29 -0
- package/README.md +96 -10
- package/dist/cli.js +17 -3
- package/dist/cli.js.map +1 -1
- package/dist/shape.cjs +201 -0
- package/dist/shape.cjs.map +1 -0
- package/dist/shape.d.cts +22 -0
- package/dist/shape.d.ts +22 -0
- package/dist/shape.js +199 -0
- package/dist/shape.js.map +1 -0
- package/package.json +14 -4
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
|
-
|
|
354
|
-
`
|
|
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
|
|
370
|
-
|
|
371
|
-
|
|
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.
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
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
|
-
|
|
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") {
|