feat: agnostic config saving (#157)

package.json

@@ -29,9 +29,10 @@
     "@commitlint/cli": "^17.0.3",
     "@commitlint/config-conventional": "^17.0.3",
     "@types/jest": "^27.5.2",
-    "@types/node": "^14.18.21",
+    "@types/node": "^14.18.33",
     "@types/webpack": "^5.0.0",
     "@types/webpack-node-externals": "^2.5.3",
+    "@types/wicg-file-system-access": "^2020.9.5",
     "@typescript-eslint/eslint-plugin": "^5.33.0",
     "@typescript-eslint/parser": "^5.33.0",
     "eslint": "^7.23.0",

src/lib/Config/index.ts

@@ -1,3 +1,4 @@
+import { isBrowser, isNode } from 'browser-or-node';
 import * as YAML from 'yaml';
 import { version as SDKVersion } from '../../../package-version.json';
 import { Generable } from '../Components';
@@ -239,6 +240,40 @@ export class Config
   get generableType(): GenerableType {
     return GenerableType.CONFIG;
   }
+
+  /**
+   * Agnostic method to save a config file to disk via Node or the Browser.
+   * Note: If you are accessing this method from the browser, it must be triggered by a user action.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/showSaveFilePicker#security}
+   * @param path - The path to write the config to. ONLY USED IN NODE.JS
+   */
+  async writeFile(path?: string) {
+    if (isBrowser) {
+      const newHandle = await window.showSaveFilePicker({
+        suggestedName: 'config.yml',
+        types: [
+          {
+            description: 'CircleCI Config YAML file',
+            accept: {
+              'text/yaml': ['.yml', '.yaml'],
+            },
+          },
+        ],
+      });
+      (await newHandle.createWritable()).write(this.stringify()).catch((e) => {
+        throw new Error(e);
+      });
+    } else if (isNode) {
+      const fsw = await import('fs/promises');
+      const filepath = path || 'config.yml';
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      await fsw.writeFile(filepath, this.stringify()).catch((e) => {
+        throw new Error(e);
+      });
+    } else {
+      throw new Error('Unsupported environment');
+    }
+  }
 }
 
 function generateList<Shape>(

tests/Config.test.ts

@@ -1,6 +1,7 @@
 import * as YAML from 'yaml';
 import * as CircleCI from '../src/index';
 import { version as SDKVersion } from '../package-version.json';
+import fs from 'fs';
 
 describe('Generate a Setup workflow config', () => {
   const myConfig = new CircleCI.Config(true).stringify();
@@ -113,3 +114,23 @@ describe('Parse a fully complete config', () => {
     expect(myConfig.generableType).toBe(CircleCI.mapping.GenerableType.CONFIG);
   });
 });
+
+describe('Save config to file in Node environment', () => {
+  const myConfig = new CircleCI.Config();
+  const executor = new CircleCI.executors.DockerExecutor('cimg/node:16.3');
+  const job = new CircleCI.Job('my-job', executor, [
+    new CircleCI.commands.Run({ command: 'echo hello world' }),
+  ]);
+  myConfig.addJob(job);
+  const myWorkflow = new CircleCI.Workflow('my-workflow');
+  myWorkflow.addJob(job);
+  myConfig.addWorkflow(myWorkflow);
+  myConfig.writeFile('/tmp/test-config.yml');
+  it('Should write a file to the specified path', () => {
+    expect(fs.existsSync('/tmp/test-config.yml')).toBe(true);
+  });
+});
+
+afterAll(() => {
+  fs.rmSync('/tmp/test-config.yml');
+});

tsconfig.json

@@ -19,7 +19,8 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "lib": ["es2017"]
+    "lib": ["es2017", "dom"],
+    "types": ["@types/wicg-file-system-access", "node", "jest"]
   },
   "include": ["src/**/*.ts", "**/*.test.ts"],
   "exclude": ["node_modules", "**/*.d.ts"],