buildx-cli 1.8.35 → 1.8.37

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 (7) hide show
  1. package/README.md +47 -7
  2. package/dist/README.md +47 -7
  3. package/dist/index.cjs +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/package.json +3 -4
  6. package/dist/templates/schema-as-code-guide.md +134 -43
  7. package/package.json +5 -5
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "buildx-cli",
3
- "version": "1.8.35",
3
+ "version": "1.8.37",
4
4
  "description": "CLI tool for BuildX API with authentication and schema synchronization",
5
5
  "type": "module",
6
6
  "main": "index.cjs",
@@ -38,7 +38,6 @@
38
38
  "@rollup/plugin-terser": "^0.4.4",
39
39
  "@types/fs-extra": "^11.0.4",
40
40
  "@types/inquirer": "^9.0.7",
41
- "@types/jest": "^29.5.6",
42
41
  "@types/node": "^20.8.0",
43
42
  "@typescript-eslint/eslint-plugin": "^8.14.0",
44
43
  "@typescript-eslint/parser": "^8.14.0",
@@ -49,14 +48,14 @@
49
48
  "eslint-import-resolver-typescript": "^3.7.0",
50
49
  "eslint-plugin-import": "^2.31.0",
51
50
  "eslint-plugin-vitest-globals": "^1.5.0",
52
- "jest": "^29.7.0",
53
51
  "madge": "^8.0.0",
54
52
  "prettier": "^3.0.3",
55
53
  "rimraf": "^6.0.1",
56
54
  "rollup": "^4.44.0",
57
55
  "rollup-plugin-dts": "^6.2.1",
58
56
  "rollup-plugin-esbuild": "^6.2.1",
59
- "tsx": "^4.20.3"
57
+ "tsx": "^4.20.3",
58
+ "vitest": "^3.2.4"
60
59
  },
61
60
  "engines": {
62
61
  "node": ">=16.0.0"
package/dist/templates/schema-as-code-guide.md CHANGED
@@ -1,46 +1,137 @@
1
- # Buildx As-Code Quick Guide
1
+ # Buildx Schema As-Code Guide
2
2
 
3
- This folder is generated for project-level collaboration between developers and AI tools.
4
3
  Project: `{{PROJECT_ID}}`
5
4
 
6
- ## Core Concepts
7
- - `Bx*` types are platform base types used in generated TypeScript.
8
- - `collections.json` is collections-as-code (deployable schema payload).
9
- - `types.ts` is developer-facing contract (editing-friendly, annotation-friendly).
10
- - `collections.manifest.json` is checksum metadata for drift/conflict checks.
11
-
12
- ## What `Bx*` Means
13
- - `BxText`, `BxLongText`, `BxNumber`, `BxDate`, `BxDateTime`, `BxChoices`, etc. map to platform field types.
14
- - `BxDataObject` / `BxDataObjects` represent cross-collection references.
15
- - `BxUser` / `BxUsers` / `BxAuth` represent user/auth-oriented structures.
16
- - `BxFiles` / `BxImages` are array-capable media types.
17
- - Some aliases are normalized by CLI during pull for consistency.
18
-
19
- ## Collection As Code Rules
20
- - `collection_id` is immutable identity. Do not rename or duplicate.
21
- - System-managed fields are runtime-only in types and are excluded from sync payload:
22
- - `createdAt`, `updatedAt`, `createdBy`, `updatedBy`
23
- - `timestamps: true` => `types.ts` includes `createdAt`/`updatedAt`.
24
- - `auditable: true` => `types.ts` includes `createdBy`/`updatedBy`.
25
- - `createdBy`/`updatedBy` follow datastore auth shape (`BxAuth`).
26
- - CLI normalizes schema for compatibility (children/ref/inherited flags/user-ref cleanup).
27
-
28
- ## Function As Code Rules
29
- - Platform runtime expects function source as async wrapper form.
30
- - Keep function files compatible with runtime wrapper constraints before push.
31
- - Use `function:pull`, `function:diff`, `function:push` to control drift and updates.
32
-
33
- ## SDK Usage (buildx-sdk)
34
- - `buildx.collections()` for schema/data collection operations.
35
- - `buildx.functions()` for function source/log updates.
36
- - Use SDK in app/runtime code; use CLI for as-code pull/convert/diff/push lifecycle.
37
-
38
- ## Where To Look Next
39
- - CLI command details: `buildx-cli/README.md`
40
- - SDK API surface: `buildx-sdk/README.md`
41
- - Runtime behavior source: datastore collection/function services
42
-
43
- ## Practical Limits
44
- - `types.ts` is a collaboration/editing artifact; `collections.json` is deployment payload.
45
- - Not every TypeScript expression can map 1:1 to platform schema semantics.
46
- - Always validate with `schema:diff` (and `--details`) before push.
5
+ This folder is generated to make schema collaboration deterministic between local code, AI tools, and remote BuildX project schema.
6
+
7
+ ## Files and Roles
8
+ - `types.ts`: human-editable schema contract.
9
+ - `collections.json`: deployable schema payload.
10
+ - `collections.manifest.json`: pull-time checksums used for remote drift checks.
11
+ - `SCHEMA_AS_CODE.md`: this guide.
12
+
13
+ Source-of-truth:
14
+ - During `schema:pull`, `collections.json` comes from remote `/project/:project_id/collections` payload (normalized only for internal/runtime keys).
15
+ - `types.ts` is generated for editing convenience and may include helper annotations.
16
+ - During `schema:types:convert`, `types.ts` is converted back into `collections.json` (with optional merge from base metadata).
17
+
18
+ ## Recommended Lifecycle
19
+ 1. Pull latest:
20
+ - `npx buildx-cli schema:pull --project-id {{PROJECT_ID}} --target-dir ./buildx/generated`
21
+ 2. Edit `types.ts` with `@bx.*` decorators when needed.
22
+ 3. Convert:
23
+ - `npx buildx-cli schema:types:convert --target-dir ./buildx/generated`
24
+ 4. Review:
25
+ - `npx buildx-cli schema:diff --project-id {{PROJECT_ID}} --target-dir ./buildx/generated --details`
26
+ 5. Push:
27
+ - `npx buildx-cli schema:push --project-id {{PROJECT_ID}} --target-dir ./buildx/generated --dry-run`
28
+ - `npx buildx-cli schema:push --project-id {{PROJECT_ID}} --target-dir ./buildx/generated`
29
+
30
+ ## Type Mapping Overview
31
+ - Scalar aliases:
32
+ - `BxText -> Text`
33
+ - `BxLongText -> LongText`
34
+ - `BxNumber -> Number`
35
+ - `BxDate -> Date`
36
+ - `BxDateTime -> DateTime`
37
+ - `BxBoolean -> Boolean`
38
+ - `BxMixed -> Mixed`
39
+ - Relation aliases:
40
+ - `Partial<Foo> | BxDataObject -> DataObject(ref=foo)`
41
+ - `Partial<Foo>[] | BxDataObject[] -> DataObjects(ref=foo)`
42
+ - Embedded:
43
+ - inline object -> `Object.propertiesScheme.children`
44
+ - inline array object -> `List.propertiesScheme.children`
45
+ - Compatibility:
46
+ - `string[]` and `BxText[]` convert to `MultipleChoices`.
47
+
48
+ ## Required and Default Semantics
49
+ - Default behavior: if `@bx.required` is not provided, converter does not force `required: true`.
50
+ - To make a field required explicitly, add `@bx.required`.
51
+ - To force not-required explicitly, use `@bx.required false`.
52
+ - Default value uses `@bx.default <json>`.
53
+
54
+ Example:
55
+
56
+ ```ts
57
+ export type Employees = {
58
+ /** @bx.required */
59
+ employee_id?: BxText;
60
+ /** @bx.required false @bx.default "active" */
61
+ status?: BxText;
62
+ };
63
+ ```
64
+
65
+ ## Decorator Reference (`@bx.*`)
66
+ - `@bx.title <text>`: set field title.
67
+ - `@bx.description <text>`: set field description.
68
+ - `@bx.required` or `@bx.required false`: explicit required toggle.
69
+ - `@bx.type <SchemaType>`: override inferred schema field type.
70
+ - `@bx.ref <collection_or_enum_key>`: set relation reference target.
71
+ - `@bx.default <json>`: set default value.
72
+ - `@bx.format <json_or_string>`: set `propertiesScheme.format`.
73
+ - `@bx.validate <json_or_string>`: set `propertiesScheme.validate`.
74
+ - `@bx.props <json-object>`: merge custom keys into `propertiesScheme`.
75
+ - `@bx.choices value:Label|value2:Label 2`: set choices for `Choices`/`MultipleChoices`.
76
+
77
+ Decorator precedence:
78
+ 1. Base inferred type from TypeScript.
79
+ 2. Apply `@bx.*` overrides.
80
+ 3. Normalize refs (enum key to collection_id when possible).
81
+ 4. Optional merge with base collections metadata (if provided to convert command).
82
+
83
+ ## Detailed Examples
84
+
85
+ ### 1) Relation with explicit ref
86
+
87
+ ```ts
88
+ export type WorkOrders = {
89
+ /** @bx.ref employees @bx.title Approver */
90
+ approver?: Partial<Employees> | BxDataObject;
91
+ };
92
+ ```
93
+
94
+ Convert result (shape):
95
+
96
+ ```json
97
+ {
98
+ "approver": {
99
+ "type": "DataObject",
100
+ "title": "Approver",
101
+ "propertiesScheme": { "ref": "employees" }
102
+ }
103
+ }
104
+ ```
105
+
106
+ ### 2) Reverse reference override
107
+
108
+ ```ts
109
+ export type Projects = {
110
+ /** @bx.type ReverseReferences @bx.ref tasks */
111
+ task_links?: Partial<Tasks>[] | BxDataObject[];
112
+ };
113
+ ```
114
+
115
+ ### 3) Embedded list with custom validation
116
+
117
+ ```ts
118
+ export type Documents = {
119
+ /** @bx.props {"minItems":1} */
120
+ approvals?: {
121
+ /** @bx.required */
122
+ officer_id?: BxText;
123
+ /** @bx.default false */
124
+ approved?: BxBoolean;
125
+ }[];
126
+ };
127
+ ```
128
+
129
+ ## System-Managed Fields
130
+ - `createdAt`, `updatedAt`, `createdBy`, `updatedBy` may appear in pulled `types.ts` when collection flags are enabled.
131
+ - These fields are runtime/system-managed and excluded from converted/pushed schema payload.
132
+
133
+ ## Practical Guardrails
134
+ - Keep `collection_id` stable.
135
+ - Run `schema:diff --details` before every push.
136
+ - Use `--no-annotate-types` only if you understand metadata-loss tradeoffs.
137
+ - Use `--base-collections-file` with convert when preserving legacy metadata is important.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "buildx-cli",
3
- "version": "1.8.35",
3
+ "version": "1.8.37",
4
4
  "description": "CLI tool for BuildX API with authentication and schema synchronization",
5
5
  "type": "module",
6
6
  "main": "index.cjs",
@@ -39,7 +39,8 @@
39
39
  "template:push": "tsx src/index.ts template:push",
40
40
  "template:diff": "tsx src/index.ts template:diff",
41
41
  "start": "node dist/index.js",
42
- "test": "jest --config jest.config.cjs",
42
+ "test": "vitest --run",
43
+ "test:watch": "vitest",
43
44
  "lint": "eslint src/**/*.ts",
44
45
  "format": "prettier --write src/**/*.ts",
45
46
  "prepublishOnly": "npm run build",
@@ -71,7 +72,6 @@
71
72
  "@rollup/plugin-terser": "^0.4.4",
72
73
  "@types/fs-extra": "^11.0.4",
73
74
  "@types/inquirer": "^9.0.7",
74
- "@types/jest": "^29.5.6",
75
75
  "@types/node": "^20.8.0",
76
76
  "@typescript-eslint/eslint-plugin": "^8.14.0",
77
77
  "@typescript-eslint/parser": "^8.14.0",
@@ -82,14 +82,14 @@
82
82
  "eslint-import-resolver-typescript": "^3.7.0",
83
83
  "eslint-plugin-import": "^2.31.0",
84
84
  "eslint-plugin-vitest-globals": "^1.5.0",
85
- "jest": "^29.7.0",
86
85
  "madge": "^8.0.0",
87
86
  "prettier": "^3.0.3",
88
87
  "rimraf": "^6.0.1",
89
88
  "rollup": "^4.44.0",
90
89
  "rollup-plugin-dts": "^6.2.1",
91
90
  "rollup-plugin-esbuild": "^6.2.1",
92
- "tsx": "^4.20.3"
91
+ "tsx": "^4.20.3",
92
+ "vitest": "^3.2.4"
93
93
  },
94
94
  "engines": {
95
95
  "node": ">=16.0.0"