@collective-intelligence/cli 0.1.15 → 0.1.17
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/README.md +179 -2
- package/dist/cli.js +84 -44
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -178,7 +178,7 @@ ci apps credentials rotate <app-fqn-or-id> --name pipeline --env-file .env.serve
|
|
|
178
178
|
ci apps credentials revoke <app-fqn-or-id> --name pipeline
|
|
179
179
|
|
|
180
180
|
# Sign in as an Organization Admin or Tenant Admin first.
|
|
181
|
-
ci api-keys upsert --principal <principal-fqn> --name pipeline --scopes
|
|
181
|
+
ci api-keys upsert --principal <principal-fqn> --name pipeline --scopes knowledge_read --env-file .env.pipeline
|
|
182
182
|
ci api-keys list --principal <principal-fqn>
|
|
183
183
|
ci api-keys get --principal <principal-fqn> --name pipeline
|
|
184
184
|
ci api-keys rotate --principal <principal-fqn> --name pipeline --env-file .env.pipeline
|
|
@@ -188,7 +188,11 @@ ci api-keys revoke --principal <principal-fqn> --name pipeline
|
|
|
188
188
|
`upsert` requires a name. For Server Credentials, omitting `--server-role`
|
|
189
189
|
restricts the credential to the app's Default Server Role. Repeat `--server-role`
|
|
190
190
|
to supply an explicit role list. API keys require at least one `--scopes` value;
|
|
191
|
-
scopes accept comma- or space-separated values and can repeat.
|
|
191
|
+
scopes accept comma- or space-separated values and can repeat. The scopes are
|
|
192
|
+
`knowledge_read`, `knowledge_manage`, `documents_read`, `documents_manage`,
|
|
193
|
+
`datasets_read`, `datasets_manage`, `automations_invoke`,
|
|
194
|
+
`benchmark_judge_invoke`, `organization_users_manage`,
|
|
195
|
+
`organization_settings_manage` and `external_apps_manage`. A rerun updates
|
|
192
196
|
only these grants and returns no secret.
|
|
193
197
|
`upsert --rotate` explicitly rotates an existing credential; creating a missing
|
|
194
198
|
credential already issues its first secret. Rotation retains the previous secret
|
|
@@ -487,6 +491,179 @@ sizes, private-map integrity, and every relative runtime import without
|
|
|
487
491
|
evaluating Extension code. Use `--private-maps <directory>` only when the
|
|
488
492
|
private maps were moved from their default directory next to the manifest.
|
|
489
493
|
|
|
494
|
+
## Generate TypeScript Schemas
|
|
495
|
+
|
|
496
|
+
`ci package codegen` writes TypeScript for the schemas that package
|
|
497
|
+
declarations declare: tool input and output, forms, workflow nodes, connections,
|
|
498
|
+
knowledge records and the other Schema Slots of each package. The command loads
|
|
499
|
+
the declarations on your machine. It needs no Backend, no network and no built
|
|
500
|
+
release.
|
|
501
|
+
|
|
502
|
+
```sh
|
|
503
|
+
ci package codegen --target zod --out ./src/generated \
|
|
504
|
+
--declaration ./src/package.ts
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Each run writes one Codegen Target:
|
|
508
|
+
|
|
509
|
+
| Target | Output |
|
|
510
|
+
| -------- | --------------------------------------------------- |
|
|
511
|
+
| `types` | Plain TypeScript types. No import. |
|
|
512
|
+
| `zod` | Zod schemas and inferred types. Needs zod 4.4+. |
|
|
513
|
+
| `effect` | `effect/Schema` schemas and types. Needs Effect v4. |
|
|
514
|
+
|
|
515
|
+
The generated types and schemas describe the wire shape (the encoded JSON), not
|
|
516
|
+
decoded runtime values. A `zod` or `effect` export is a `const` schema and a
|
|
517
|
+
`type` of the same name.
|
|
518
|
+
|
|
519
|
+
**Generated schemas are not runtime validation authority.** They are a
|
|
520
|
+
convenience for your own code. The Backend host validates every request and
|
|
521
|
+
payload, and a generated schema never replaces that check. Every generated file
|
|
522
|
+
says so in its header.
|
|
523
|
+
|
|
524
|
+
### Settings
|
|
525
|
+
|
|
526
|
+
The command reads three settings. Pass a flag, or set the value in an optional
|
|
527
|
+
`ci.codegen` section of the `package.json` in the current directory:
|
|
528
|
+
|
|
529
|
+
```json
|
|
530
|
+
{
|
|
531
|
+
"ci": {
|
|
532
|
+
"codegen": {
|
|
533
|
+
"target": "zod",
|
|
534
|
+
"out": "./src/generated",
|
|
535
|
+
"declaration": ["./src/package.ts"]
|
|
536
|
+
}
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
| Flag | `ci.codegen` key | Meaning |
|
|
542
|
+
| --------------- | ---------------- | --------------------------------------------------------------------------- |
|
|
543
|
+
| `--target` | `target` | `types`, `zod` or `effect`. |
|
|
544
|
+
| `--out` | `out` | The Codegen Output Root, the folder that holds one subfolder per package. |
|
|
545
|
+
| `--declaration` | `declaration` | A declaration module. Repeat the flag, or give an array in `package.json`. |
|
|
546
|
+
| `--check` | none | Run the Schema Codegen Check. It writes nothing. |
|
|
547
|
+
| `--verbose` | none | Print every warning. See [Summary and exit codes](#summary-and-exit-codes). |
|
|
548
|
+
|
|
549
|
+
- A flag replaces the same setting from `package.json`. Any `--declaration`
|
|
550
|
+
flag replaces the whole `declaration` list.
|
|
551
|
+
- The command reads only the `package.json` in the current directory. It does
|
|
552
|
+
not search parent folders and reads no other configuration file.
|
|
553
|
+
- Relative paths resolve against the current directory.
|
|
554
|
+
- `target`, `out` and at least one `declaration` are required. A missing
|
|
555
|
+
setting or an unknown target stops the command before it reads a
|
|
556
|
+
declaration.
|
|
557
|
+
- A declaration module exports a `PackageDefinition` or an array of them, as
|
|
558
|
+
`packageDefinitions`, `packageDefinition` or the default export.
|
|
559
|
+
|
|
560
|
+
### Output
|
|
561
|
+
|
|
562
|
+
For each package, the command writes one Generated Schema File:
|
|
563
|
+
|
|
564
|
+
```text
|
|
565
|
+
<out>/
|
|
566
|
+
└── <package fqn>/
|
|
567
|
+
└── <target>.ts
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
The folder name is the package `fqn` from its manifest. One run writes one
|
|
571
|
+
target file for each package. The files of the other targets in the same folder
|
|
572
|
+
stay as they are, so you can run the command once for each target.
|
|
573
|
+
|
|
574
|
+
Every file starts with a fixed header:
|
|
575
|
+
|
|
576
|
+
```ts
|
|
577
|
+
// @generated
|
|
578
|
+
// Target: zod
|
|
579
|
+
// Package: acme.billing
|
|
580
|
+
// Version: 1.0.0
|
|
581
|
+
// Generated schemas are a convenience and not runtime validation authority.
|
|
582
|
+
// The backend host validates.
|
|
583
|
+
```
|
|
584
|
+
|
|
585
|
+
The `effect` header adds one line: closed objects reject excess keys only
|
|
586
|
+
through the decode option `onExcessProperty: "error"`. The header has no tool
|
|
587
|
+
version, timestamp or hash, so the same declarations always give the same
|
|
588
|
+
bytes. The tool prints its own canonical format and does not call your
|
|
589
|
+
formatter.
|
|
590
|
+
|
|
591
|
+
Commit the generated files. Run the command again when a declaration changes.
|
|
592
|
+
|
|
593
|
+
### Check that files are current
|
|
594
|
+
|
|
595
|
+
`--check` is the Schema Codegen Check. It generates the files in memory,
|
|
596
|
+
compares them byte for byte with the files on disk and writes nothing. The
|
|
597
|
+
command exits with a non-zero code when one file of the run is missing or
|
|
598
|
+
different. Use it in CI or a pre-commit hook:
|
|
599
|
+
|
|
600
|
+
```sh
|
|
601
|
+
ci package codegen --check
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
The check covers only the package subfolders and the target of this run. It
|
|
605
|
+
does not look at other targets or at other folders under the output root.
|
|
606
|
+
|
|
607
|
+
### Unsupported schema constructs
|
|
608
|
+
|
|
609
|
+
The command never degrades a shape silently. It fails, and writes no file,
|
|
610
|
+
for a keyword that it cannot express (for example `not`, `if`,
|
|
611
|
+
`patternProperties` or `contains`), an unknown keyword that does not start with
|
|
612
|
+
`x-`, a remote or recursive `$ref`, two exports with one name, and a package
|
|
613
|
+
`fqn` that two declarations declare. One run reports every error with the schema
|
|
614
|
+
name, a JSON Pointer and the keyword. A keyword that starts with `x-` is
|
|
615
|
+
ignored.
|
|
616
|
+
|
|
617
|
+
A validation-only keyword that a target cannot check is kept as an annotation
|
|
618
|
+
and gives a warning:
|
|
619
|
+
|
|
620
|
+
- `types`: validation keywords become JSDoc tags.
|
|
621
|
+
- `zod`: `uniqueItems`, `minProperties`, `maxProperties` and formats other than
|
|
622
|
+
`date-time`, `email`, `uuid` and `uri` stay as `.meta` data.
|
|
623
|
+
- `effect`: closed objects (`additionalProperties: false`) are not enforced,
|
|
624
|
+
because `Schema.Struct` has no closed object. Only `format: uuid` is a format
|
|
625
|
+
check; other formats stay as annotations.
|
|
626
|
+
|
|
627
|
+
The [library README](../schema-codegen/README.md#keywords) lists the supported
|
|
628
|
+
and failing keywords and the limits of each target.
|
|
629
|
+
|
|
630
|
+
### Summary and exit codes
|
|
631
|
+
|
|
632
|
+
The command prints one line for each file: `written` or `unchanged` with the
|
|
633
|
+
schema count, or with `--check` the status `current`, `missing` or `different`.
|
|
634
|
+
Below a file, each warning kind prints once with a count and up to three example
|
|
635
|
+
locations. `closed_object_unenforced` prints only its count. `--verbose` prints
|
|
636
|
+
every warning on its own line.
|
|
637
|
+
|
|
638
|
+
- Warnings never change the exit code.
|
|
639
|
+
- Errors and a stale `--check` give a non-zero exit code.
|
|
640
|
+
|
|
641
|
+
### How the command writes files
|
|
642
|
+
|
|
643
|
+
- The command overwrites only a file that starts with the generated header
|
|
644
|
+
comment (`@generated`). If a file of this run exists without it and differs
|
|
645
|
+
from the new output, the command stops before it writes any file.
|
|
646
|
+
- The command never deletes a file or a folder.
|
|
647
|
+
- It writes each changed file to a temporary file, then renames it. If a write
|
|
648
|
+
or a rename fails, a final file is still whole (old or new), but
|
|
649
|
+
`<target>.ts.<pid>.tmp` files can stay. Delete them by hand.
|
|
650
|
+
- A generation error, a duplicate package `fqn` or a refused overwrite writes no
|
|
651
|
+
file.
|
|
652
|
+
|
|
653
|
+
### Operating rules
|
|
654
|
+
|
|
655
|
+
- **Run all declarations in one command.** The check and the overwrite rule
|
|
656
|
+
cover only the packages of this run. Give every declaration of the output
|
|
657
|
+
root to the same command, with repeated `--declaration` flags or a
|
|
658
|
+
`declaration` array.
|
|
659
|
+
- **Delete the folder of a removed package by hand.** The command ignores
|
|
660
|
+
folders of packages outside the run, so it never reports a package that you
|
|
661
|
+
removed from every declaration.
|
|
662
|
+
- **Exclude generated files from your formatter and linter.** A formatter
|
|
663
|
+
changes the bytes, so `--check` fails. A linter reports style problems in
|
|
664
|
+
code that you do not edit. Add the output folder to the ignore list of each
|
|
665
|
+
tool.
|
|
666
|
+
|
|
490
667
|
## Development Sessions
|
|
491
668
|
|
|
492
669
|
Set an authenticated management token and name the Backend and every Host
|