@collective-intelligence/cli 0.1.14 → 0.1.16

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.
Files changed (3) hide show
  1. package/README.md +179 -2
  2. package/dist/cli.js +84 -44
  3. 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 data_read --env-file .env.pipeline
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. A rerun updates
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