Release new kcl-lib and derive-docs (#5344)

* Remove DEV=false from .env.production

* And process.env.DEV too

* A snapshot a day keeps the bugs away! 📷🐛 (OS: namespace-profile-ubuntu-8-cores)

* Bad bot

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.env.development

@@ -2,8 +2,8 @@ NODE_ENV=development
 DEV=true
 VITE_KC_API_WS_MODELING_URL=wss://api.dev.zoo.dev/ws/modeling/commands
 VITE_KC_API_BASE_URL=https://api.dev.zoo.dev
-BASE_URL=https://api.dev.zoo.dev
 VITE_KC_SITE_BASE_URL=https://dev.zoo.dev
+VITE_KC_SITE_APP_URL=https://app.dev.zoo.dev
 VITE_KC_SKIP_AUTH=false
 VITE_KC_CONNECTION_TIMEOUT_MS=5000
 # ONLY add your token in .env.development.local if you want to skip auth, otherwise this token takes precedence!

.env.production

@@ -1,5 +1,7 @@
+NODE_ENV=production
 VITE_KC_API_WS_MODELING_URL=wss://api.zoo.dev/ws/modeling/commands
 VITE_KC_API_BASE_URL=https://api.zoo.dev
 VITE_KC_SITE_BASE_URL=https://zoo.dev
+VITE_KC_SITE_APP_URL=https://app.zoo.dev
 VITE_KC_SKIP_AUTH=false
 VITE_KC_CONNECTION_TIMEOUT_MS=15000

.eslintrc

@@ -29,6 +29,13 @@
         {
           "name": "isNaN",
           "message": "Use Number.isNaN() instead."
+        },
+      ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          "selector": "CallExpression[callee.object.name='Array'][callee.property.name='isArray']",
+          "message": "Use isArray() in lib/utils.ts instead of Array.isArray()."
         }
       ],
       "semi": [

.github/workflows/build-apps.yml

@@ -134,8 +134,6 @@ jobs:
           max_attempts: 3
           command: yarn install
 
-      - run: yarn tronb:vite
-
       - name: Prepare certificate and variables (Windows only)
         if: ${{ (env.IS_RELEASE == 'true' || env.IS_NIGHTLY == 'true') && matrix.os == 'windows-2022' }}
         run: |
@@ -165,8 +163,8 @@ jobs:
       - name: Build the app (debug)
         if: ${{ env.IS_RELEASE == 'false' && env.IS_NIGHTLY == 'false' }}
         # electron-builder doesn't have a concept of release vs debug,
-        # this is just not doing any codesign or release yml generation
+        # this is just not doing any codesign or release yml generation, and points to dev infra
-        run: yarn electron-builder --config
+        run: yarn tronb:package:dev
 
       - name: Build the app (release)
         if: ${{ env.IS_RELEASE == 'true' || env.IS_NIGHTLY == 'true' }}
@@ -185,7 +183,7 @@ jobs:
         with:
           timeout_minutes: 10
           max_attempts: 3
-          command: yarn electron-builder --config --publish always
+          command: yarn tronb:package:prod
 
       - name: List artifacts in out/
         run: ls -R out
@@ -246,7 +244,7 @@ jobs:
         with:
           timeout_minutes: 10
           max_attempts: 3
-          command: yarn electron-builder --config --publish always
+          command: yarn tronb:package:prod
 
       - uses: actions/upload-artifact@v4
         if: ${{ env.IS_RELEASE == 'true' }}
@@ -390,19 +388,19 @@ jobs:
 
       - name: Authenticate to Google Cloud
         if: ${{ env.IS_NIGHTLY == 'true' }}
-        uses: 'google-github-actions/auth@v2.1.7'
+        uses: 'google-github-actions/auth@v2.1.8'
         with:
           credentials_json: '${{ secrets.GOOGLE_CLOUD_DL_SA }}'
 
       - name: Set up Google Cloud SDK
         if: ${{ env.IS_NIGHTLY == 'true' }}
-        uses: google-github-actions/setup-gcloud@v2.1.2
+        uses: google-github-actions/setup-gcloud@v2.1.4
         with:
           project_id: ${{ env.GOOGLE_CLOUD_PROJECT_ID }}
 
       - name: Upload nightly files to public bucket
         if: ${{ env.IS_NIGHTLY == 'true' }}
-        uses: google-github-actions/upload-cloud-storage@v2.2.1
+        uses: google-github-actions/upload-cloud-storage@v2.2.2
         with:
           path: out
           glob: '*'

.github/workflows/e2e-tests.yml

@@ -3,7 +3,6 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -46,7 +45,15 @@ jobs:
     runs-on: ${{ matrix.os }}
     needs: check-rust-changes
     steps:
+    - uses: actions/create-github-app-token@v1
+      id: app-token
+      with:
+        app-id: ${{ secrets.MODELING_APP_GH_APP_ID }}
+        private-key: ${{ secrets.MODELING_APP_GH_APP_PRIVATE_KEY }}
+        owner: ${{ github.repository_owner }}
     - uses: actions/checkout@v4
+      with:
+        token: ${{ steps.app-token.outputs.token }}
     - uses: actions/setup-node@v4
       with:
         node-version-file: '.nvmrc'
@@ -123,9 +130,9 @@ jobs:
       if: steps.download-wasm.outcome == 'failure'
       shell: bash
       run: yarn build:wasm
-    - name: build electron
+    - name: build web
       shell: bash
-      run: yarn tron:package
+      run: yarn tronb:vite:dev
     - name: Run ubuntu/chrome snapshots
       if: ${{ matrix.os == 'namespace-profile-ubuntu-8-cores' && matrix.shardIndex == 1 }}
       shell: bash
@@ -153,11 +160,11 @@ jobs:
       continue-on-error: true
       run: rm -r test-results
     - name: check for changes
-      if: ${{ matrix.os == 'namespace-profile-ubuntu-8-cores' && matrix.shardIndex == 1 }}
+      if: ${{ matrix.os == 'namespace-profile-ubuntu-8-cores' && matrix.shardIndex == 1 && github.ref != 'refs/heads/main' }}
       shell: bash
       id: git-check
       run: |
-          git add .
+          git add e2e/playwright/snapshot-tests.spec.ts-snapshots
           if git status | grep -q "Changes to be committed"
           then echo "modified=true" >> $GITHUB_OUTPUT
           else echo "modified=false" >> $GITHUB_OUTPUT
@@ -166,14 +173,14 @@ jobs:
       if: steps.git-check.outputs.modified == 'true'
       shell: bash
       run: |
-        git add .
+        git add e2e/playwright/snapshot-tests.spec.ts-snapshots
         git config --local user.email "github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
         git remote set-url origin https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git
         git fetch origin
         echo ${{ github.head_ref }}
         git checkout ${{ github.head_ref }}
-        git commit -am "A snapshot a day keeps the bugs away! 📷🐛 (OS: ${{matrix.os}})" || true
+        git commit -m "A snapshot a day keeps the bugs away! 📷🐛 (OS: ${{matrix.os}})" || true
         git push
         git push origin ${{ github.head_ref }}
     # only upload artifacts if there's actually changes

.github/workflows/publish-apps-release.yml

@@ -108,17 +108,17 @@ jobs:
         run: yarn files:set-notes
 
       - name: Authenticate to Google Cloud
-        uses: 'google-github-actions/auth@v2.1.7'
+        uses: 'google-github-actions/auth@v2.1.8'
         with:
           credentials_json: '${{ secrets.GOOGLE_CLOUD_DL_SA }}'
 
       - name: Set up Google Cloud SDK
-        uses: google-github-actions/setup-gcloud@v2.1.2
+        uses: google-github-actions/setup-gcloud@v2.1.4
         with:
           project_id: ${{ env.GOOGLE_CLOUD_PROJECT_ID }}
 
       - name: Upload release files to public bucket
-        uses: google-github-actions/upload-cloud-storage@v2.2.1
+        uses: google-github-actions/upload-cloud-storage@v2.2.2
         with:
           path: out
           glob: '*'

.gitignore

@@ -25,6 +25,7 @@ yarn-error.log*
 
 .idea
 .vscode
+.helix
 src/wasm-lib/.idea
 src/wasm-lib/.vscode
 
@@ -44,7 +45,7 @@ e2e/playwright/temp3.png
 e2e/playwright/export-snapshots/*
 !e2e/playwright/export-snapshots/*.png
 
-
+/kcl-samples
 /test-results/
 /playwright-report/
 /blob-report/

.helix/config.toml

@@ -0,0 +1,2 @@
+[editor]
+auto-format = true

.helix/languages.toml

@@ -0,0 +1,10 @@
+[language-server.eslint]
+args = ["--stdio"]
+command = "vscode-eslint-language-server"
+
+[[language]]
+name = "typescript"
+auto-format = true
+formatter = { command = "node_modules/.bin/prettier", args = ["--parser", "typescript"] }
+language-servers = [ { name = "eslint", only-features = [ "diagnostics" ] }, "typescript-language-server" ]
+

README.md

@@ -101,7 +101,7 @@ This will start the application and hot-reload on changes.
 
 Devtools can be opened with the usual Cmd-Opt-I (Mac) or Ctrl-Shift-I (Linux and Windows).
 
-To build, run `yarn tron:package`.
+To build with electron-builder, run `yarn tronb:package:dev` (or `yarn tronb:package:prod` to point to the .env.production variables)
 
 ## Checking out commits / Bisecting
 

docs/kcl/fillet.md

@@ -36,12 +36,12 @@ filletRadius = 2
 
 mountingPlateSketch = startSketchOn("XY")
   |> startProfileAt([-width / 2, -length / 2], %)
-  |> lineTo([width / 2, -length / 2], %, $edge1)
+  |> line(endAbsolute = [width / 2, -length / 2], tag = $edge1)
-  |> lineTo([width / 2, length / 2], %, $edge2)
+  |> line(endAbsolute = [width / 2, length / 2], tag = $edge2)
-  |> lineTo([-width / 2, length / 2], %, $edge3)
+  |> line(endAbsolute = [-width / 2, length / 2], tag = $edge3)
-  |> close(%, $edge4)
+  |> close(tag = $edge4)
 
-mountingPlate = extrude(thickness, mountingPlateSketch)
+mountingPlate = extrude(mountingPlateSketch, length = thickness)
   |> fillet({
        radius = filletRadius,
        tags = [
@@ -63,12 +63,12 @@ filletRadius = 1
 
 mountingPlateSketch = startSketchOn("XY")
   |> startProfileAt([-width / 2, -length / 2], %)
-  |> lineTo([width / 2, -length / 2], %, $edge1)
+  |> line(endAbsolute = [width / 2, -length / 2], tag = $edge1)
-  |> lineTo([width / 2, length / 2], %, $edge2)
+  |> line(endAbsolute = [width / 2, length / 2], tag = $edge2)
-  |> lineTo([-width / 2, length / 2], %, $edge3)
+  |> line(endAbsolute = [-width / 2, length / 2], tag = $edge3)
-  |> close(%, $edge4)
+  |> close(tag = $edge4)
 
-mountingPlate = extrude(thickness, mountingPlateSketch)
+mountingPlate = extrude(mountingPlateSketch, length = thickness)
   |> fillet({
        radius = filletRadius,
        tolerance = 0.000001,

docs/kcl/import.md

@@ -14,8 +14,6 @@ For formats lacking unit data (such as STL, OBJ, or PLY files), the default unit
 
 Note: The import command currently only works when using the native Modeling App.
 
-For importing KCL functions using the `import` statement, see the docs on [KCL modules](/docs/kcl/modules).
-
 ```js
 import(file_path: String, options?: ImportFormat) -> ImportedGeometry
 ```

docs/kcl/index.md

@@ -58,7 +58,6 @@ layout: manual
 * [`legAngY`](kcl/legAngY)
 * [`legLen`](kcl/legLen)
 * [`line`](kcl/line)
-* [`lineTo`](kcl/lineTo)
 * [`ln`](kcl/ln)
 * [`loft`](kcl/loft)
 * [`log`](kcl/log)

docs/kcl/loft.md

@@ -34,18 +34,18 @@ loft(sketches: [Sketch], v_degree: NonZeroU32, bez_approximate_rational: bool, b
 // Loft a square and a triangle.
 squareSketch = startSketchOn('XY')
   |> startProfileAt([-100, 200], %)
-  |> line([200, 0], %)
+  |> line(end = [200, 0])
-  |> line([0, -200], %)
+  |> line(end = [0, -200])
-  |> line([-200, 0], %)
+  |> line(end = [-200, 0])
-  |> lineTo([profileStartX(%), profileStartY(%)], %)
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-  |> close(%)
+  |> close()
 
 triangleSketch = startSketchOn(offsetPlane('XY', 75))
   |> startProfileAt([0, 125], %)
-  |> line([-15, -30], %)
+  |> line(end = [-15, -30])
-  |> line([30, 0], %)
+  |> line(end = [30, 0])
-  |> lineTo([profileStartX(%), profileStartY(%)], %)
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-  |> close(%)
+  |> close()
 
 loft([squareSketch, triangleSketch])
 ```
@@ -56,11 +56,11 @@ loft([squareSketch, triangleSketch])
 // Loft a square, a circle, and another circle.
 squareSketch = startSketchOn('XY')
   |> startProfileAt([-100, 200], %)
-  |> line([200, 0], %)
+  |> line(end = [200, 0])
-  |> line([0, -200], %)
+  |> line(end = [0, -200])
-  |> line([-200, 0], %)
+  |> line(end = [-200, 0])
-  |> lineTo([profileStartX(%), profileStartY(%)], %)
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-  |> close(%)
+  |> close()
 
 circleSketch0 = startSketchOn(offsetPlane('XY', 75))
   |> circle({ center = [0, 100], radius = 50 }, %)
@@ -81,11 +81,11 @@ loft([
 // Loft a square, a circle, and another circle with options.
 squareSketch = startSketchOn('XY')
   |> startProfileAt([-100, 200], %)
-  |> line([200, 0], %)
+  |> line(end = [200, 0])
-  |> line([0, -200], %)
+  |> line(end = [0, -200])
-  |> line([-200, 0], %)
+  |> line(end = [-200, 0])
-  |> lineTo([profileStartX(%), profileStartY(%)], %)
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-  |> close(%)
+  |> close()
 
 circleSketch0 = startSketchOn(offsetPlane('XY', 75))
   |> circle({ center = [0, 100], radius = 50 }, %)

docs/kcl/patternTransform2d.md

@@ -9,7 +9,7 @@ Just like patternTransform, but works on 2D sketches not 3D solids.
 
 
 ```js
-patternTransform2d(total_instances: integer, transform_function: FunctionParam, solid_set: SketchSet) -> [Sketch]
+patternTransform2d(total_instances: integer, transform_function: FunctionParam, solid_set: SketchSet, use_original?: bool) -> [Sketch]
 ```
 
 
@@ -20,6 +20,7 @@ patternTransform2d(total_instances: integer, transform_function: FunctionParam,
 | `total_instances` | `integer` |  | Yes |
 | `transform_function` | `FunctionParam` |  | Yes |
 | `solid_set` | [`SketchSet`](/docs/kcl/types/SketchSet) | A sketch or a group of sketches. | Yes |
+| `use_original` | `bool` |  | No |
 
 ### Returns
 

docs/kcl/types.md

@@ -47,21 +47,6 @@ myObj = { a = 0, b = "thing" }
 We support two different ways of getting properties from objects, you can call
 `myObj.a` or `myObj["a"]` both work.
 
-
-## Functions
-
-We also have support for defining your own functions. Functions can take in any
-type of argument. Below is an example of the syntax:
-
-```
-fn myFn(x) {
-  return x
-}
-```
-
-As you can see above `myFn` just returns whatever it is given.
-
-
 ## Binary expressions
 
 You can also do math! Let's show an example below:
@@ -76,6 +61,120 @@ You can nest expressions in parenthesis as well:
 myMathExpression = 3 + (1 * 2 / (3 - 7))
 ```
 
+## Functions
+
+We also have support for defining your own functions. Functions can take in any
+type of argument. Below is an example of the syntax:
+
+```
+fn myFn(x) {
+  return x
+}
+```
+
+As you can see above `myFn` just returns whatever it is given.
+
+KCL's early drafts used positional arguments, but we now use keyword arguments. If you declare a
+function like this:
+
+```
+fn add(left, right) {
+  return left + right
+}
+```
+
+You can call it like this:
+
+```
+total = add(left = 1, right = 2)
+```
+
+Functions can also declare one *unlabeled* arg. If you do want to declare an unlabeled arg, it must
+be the first arg declared.
+
+```
+// The @ indicates an argument can be used without a label.
+// Note that only the first argument can use @.
+fn increment(@x) {
+  return x + 1
+}
+
+fn add(@x, delta) {
+  return x + delta
+}
+
+two = increment(1)
+three = add(1, delta = 2)
+```
+
+## Pipelines
+
+It can be hard to read repeated function calls, because of all the nested brackets.
+
+```
+i = 1
+x = h(g(f(i)))
+```
+
+You can make this easier to read by breaking it into many declarations, but that is a bit annoying.
+
+```
+i  = 1
+x0 = f(i)
+x1 = g(x0)
+x  = h(x1)
+```
+
+Instead, you can use the pipeline operator (`|>`) to simplify this.
+
+Basically, `x |> f(%)` is a shorthand for `f(x)`. The left-hand side of the `|>` gets put into
+the `%` in the right-hand side.
+
+So, this means `x |> f(%) |> g(%)` is shorthand for `g(f(x))`. The code example above, with its
+somewhat-clunky `x0` and `x1` constants could be rewritten as
+
+```
+i = 1
+x = i
+|> f(%)
+|> g(%)
+|> h(%)
+```
+
+This helps keep your code neat and avoid unnecessary declarations.
+
+## Pipelines and keyword arguments
+
+Say you have a long pipeline of sketch functions, like this:
+
+```
+startSketch()
+|> line(%, end = [3, 4])
+|> line(%, end = [10, 10])
+|> line(%, end = [-13, -14])
+|> close(%)
+```
+
+In this example, each function call outputs a sketch, and it gets put into the next function call via
+the `%`, into the first (unlabeled) argument.
+
+If a function call uses an unlabeled first parameter, it will default to `%` if it's not given. This
+means that `|> line(%, end = [3, 4])` and `|> line(end = [3, 4])` are equivalent! So the above
+could be rewritten as 
+
+```
+startSketch()
+|> line(end = [3, 4])
+|> line(end = [10, 10])
+|> line(end = [-13, -14])
+|> close()
+```
+
+Note that we are still in the process of migrating KCL's standard library to use keyword arguments. So some
+functions are still unfortunately using positional arguments. We're moving them over, so keep checking back.
+Some functions like `angledLine`, `startProfileAt` etc are still using the old positional argument syntax.
+Check the docs page for each function and look at its examples to see.
+
 ## Tags
 
 Tags are used to give a name (tag) to a specific path.
@@ -88,17 +187,17 @@ way:
 ```
 startSketchOn('XZ')
   |> startProfileAt(origin, %)
-  |> angledLine([0, 191.26], %, $rectangleSegmentA001)
+  |> angledLine({angle = 0, length = 191.26}, %, $rectangleSegmentA001)
-  |> angledLine([
+  |> angledLine({
-       segAng(rectangleSegmentA001) - 90,
+       angle = segAng(rectangleSegmentA001) - 90,
-       196.99
+       length = 196.99,
-     ], %, $rectangleSegmentB001)
+     }, %, $rectangleSegmentB001)
-  |> angledLine([
+  |> angledLine({
-       segAng(rectangleSegmentA001),
+       angle = segAng(rectangleSegmentA001),
-       -segLen(rectangleSegmentA001)
+       length = -segLen(rectangleSegmentA001),
-     ], %, $rectangleSegmentC001)
+     }, %, $rectangleSegmentC001)
-  |> lineTo([profileStartX(%), profileStartY(%)], %)
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-  |> close(%)
+  |> close()
 ```
 
 ### Tag Identifier
@@ -121,17 +220,17 @@ However if the code was written like this:
 fn rect(origin) {
   return startSketchOn('XZ')
     |> startProfileAt(origin, %)
-    |> angledLine([0, 191.26], %, $rectangleSegmentA001)
+    |> angledLine({angle = 0, length = 191.26}, %, $rectangleSegmentA001)
-    |> angledLine([
+    |> angledLine({
-         segAng(rectangleSegmentA001) - 90,
+         angle = segAng(rectangleSegmentA001) - 90,
-         196.99
+         length = 196.99
-       ], %, $rectangleSegmentB001)
+       }, %, $rectangleSegmentB001)
-    |> angledLine([
+    |> angledLine({
-         segAng(rectangleSegmentA001),
+         angle = segAng(rectangleSegmentA001),
-         -segLen(rectangleSegmentA001)
+         length = -segLen(rectangleSegmentA001)
-       ], %, $rectangleSegmentC001)
+       }, %, $rectangleSegmentC001)
-    |> lineTo([profileStartX(%), profileStartY(%)], %)
+    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-    |> close(%)
+    |> close()
 }
 
 rect([0, 0])
@@ -149,17 +248,17 @@ For example the following code works.
 fn rect(origin) {
   return startSketchOn('XZ')
     |> startProfileAt(origin, %)
-    |> angledLine([0, 191.26], %, $rectangleSegmentA001)
+    |> angledLine({angle = 0, length = 191.26}, %, $rectangleSegmentA001)
-    |> angledLine([
+    |> angledLine({
-         segAng(rectangleSegmentA001) - 90,
+         angle = segAng(rectangleSegmentA001) - 90,
-         196.99
+         length = 196.99
-       ], %, $rectangleSegmentB001)
+       }, %, $rectangleSegmentB001)
-    |> angledLine([
+    |> angledLine({
-         segAng(rectangleSegmentA001),
+         angle = segAng(rectangleSegmentA001),
-         -segLen(rectangleSegmentA001)
+         length = -segLen(rectangleSegmentA001)
-       ], %, $rectangleSegmentC001)
+       }, %, $rectangleSegmentC001)
-    |> lineTo([profileStartX(%), profileStartY(%)], %)
+    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-    |> close(%)
+    |> close()
 }
 
 rect([0, 0])

docs/kcl/types/ArtifactId.md

@@ -0,0 +1,15 @@
+---
+title: "ArtifactId"
+excerpt: ""
+layout: manual
+---
+
+
+**Type:** `string` (`uuid`)
+
+
+
+
+
+
+