fix(docs/upload): add safeguard if projects have bidi enabled

__tests__/commands/docs/__snapshots__/upload.test.ts.snap

@@ -1,5 +1,49 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`rdme docs upload > given that ReadMe project has bidirection sync set up > should error if validation is not skipped 1`] = `
+{
+  "error": [Error: Bi-directional syncing is enabled for this project. Uploading these docs will overwrite what's currently synced from Git. To proceed with the upload, re-run this command with the \`--skip-validation\` flag.],
+  "stderr": "",
+  "stdout": "",
+}
+`;
+
+exports[`rdme docs upload > given that ReadMe project has bidirection sync set up > should handle an error if /projects/me returns an error 1`] = `
+{
+  "error": [APIv2Error: ReadMe API error: The API key couldn't be located.
+
+The API key you passed in (bad-api-key) doesn't match any keys we have in our system. API keys must be passed in via Bearer token. You can get your API key in Configuration > API Key, or in the docs.],
+  "stderr": "",
+  "stdout": "",
+}
+`;
+
+exports[`rdme docs upload > given that ReadMe project has bidirection sync set up > should upload if validation is skipped 1`] = `
+{
+  "result": {
+    "created": [
+      {
+        "filePath": "__tests__/__fixtures__/docs/new-docs/new-doc.md",
+        "response": {},
+        "result": "created",
+        "slug": "new-doc",
+      },
+    ],
+    "failed": [],
+    "skipped": [],
+    "updated": [],
+  },
+  "stderr": " ›   Warning: Skipping pre-upload validation of the Markdown file(s). This is 
+ ›   not recommended.
+- 🚀 Uploading files to ReadMe...
+✔ 🚀 Uploading files to ReadMe... done!
+",
+  "stdout": "🌱 Successfully created 1 page(s) in ReadMe:
+   - new-doc (__tests__/__fixtures__/docs/new-docs/new-doc.md)
+",
+}
+`;
+
 exports[`rdme docs upload > given that the file path is a directory > given that the directory contains parent/child docs > should upload parents before children 1`] = `
 {
   "result": {

__tests__/commands/docs/upload.test.ts

@@ -24,6 +24,9 @@ describe('rdme docs upload', () => {
       categories: {},
       parentPages: {},
     });
+    getAPIv2Mock({ authorization }).get('/projects/me').reply(200, {
+      data: {},
+    });
     vi.spyOn(fs, 'writeFileSync').mockImplementation(() => {});
   });
 
@@ -195,6 +198,10 @@ describe('rdme docs upload', () => {
           })
           .reply(201, {});
 
+        const projectsMeMock = getAPIv2Mock({ authorization }).get('/projects/me').reply(200, {
+          data: {},
+        });
+
         prompts.inject([true]);
 
         const result = await run(['__tests__/__fixtures__/docs/mixed-docs/legacy-category.md', '--key', key]);
@@ -208,6 +215,7 @@ describe('rdme docs upload', () => {
 
         mappingsMock.done();
         mock.done();
+        projectsMeMock.done();
       });
 
       it('should exit if the user declines to fix the issues', async () => {
@@ -289,20 +297,29 @@ describe('rdme docs upload', () => {
           })
           .reply(201, {});
 
+        const projectsMeMock = getAPIv2MockForGHA({ authorization }).get('/projects/me').reply(200, {
+          data: {},
+        });
+
         const result = await run(['__tests__/__fixtures__/docs/new-docs/new-doc.md', '--key', key]);
 
         expect(result).toMatchSnapshot();
         expect(fs.writeFileSync).not.toHaveBeenCalled();
 
         headMock.done();
         postMock.done();
+        projectsMeMock.done();
       });
 
       it('should error out if the file has validation errors', async () => {
+        const projectsMeMock = getAPIv2MockForGHA({ authorization }).get('/projects/me').reply(200, {
+          data: {},
+        });
         const result = await run(['__tests__/__fixtures__/docs/mixed-docs/legacy-category.md', '--key', key]);
 
         expect(result).toMatchSnapshot();
         expect(fs.writeFileSync).not.toHaveBeenCalled();
+        projectsMeMock.done();
       });
     });
 
@@ -508,4 +525,85 @@ describe('rdme docs upload', () => {
       mock.done();
     });
   });
+
+  describe('given that ReadMe project has bidirection sync set up', () => {
+    it('should error if validation is not skipped', async () => {
+      nock.cleanAll();
+
+      const mock = getAPIv2Mock({ authorization })
+        .get('/projects/me')
+        .reply(200, {
+          data: { git: { connection: { status: 'active' } } },
+        });
+
+      const result = await run(['__tests__/__fixtures__/docs/new-docs/new-doc.md', '--key', key]);
+
+      expect(result).toMatchSnapshot();
+      expect(fs.writeFileSync).not.toHaveBeenCalled();
+
+      mock.done();
+    });
+
+    it('should upload if validation is skipped', async () => {
+      nock.cleanAll();
+
+      const mock = getAPIv2Mock({ authorization })
+        .head('/versions/1.2.3/guides/new-doc')
+        .reply(404)
+        .post('/versions/1.2.3/guides', {
+          category: { uri: '/versions/1.2.3/categories/guides/category-slug' },
+          slug: 'new-doc',
+          title: 'This is the document title',
+          content: { body: '\nBody\n' },
+        })
+        .reply(201, {});
+
+      const projectsMeMock = getAPIv2Mock({ authorization })
+        .get('/projects/me')
+        .reply(200, {
+          data: { git: { connection: { status: 'active' } } },
+        });
+
+      const result = await run([
+        '__tests__/__fixtures__/docs/new-docs/new-doc.md',
+        '--key',
+        key,
+        '--version',
+        '1.2.3',
+        '--skip-validation',
+      ]);
+
+      expect(result).toMatchSnapshot();
+      expect(fs.writeFileSync).not.toHaveBeenCalled();
+
+      mock.done();
+      projectsMeMock.done();
+    });
+
+    it('should handle an error if /projects/me returns an error', async () => {
+      nock.cleanAll();
+
+      const mock = getAPIv2Mock({ authorization: 'Bearer bad-api-key' })
+        .get('/projects/me')
+        .reply(401, {
+          title: "The API key couldn't be located.",
+          detail:
+            "The API key you passed in (bad-api-key) doesn't match any keys we have in our system. API keys must be passed in via Bearer token. You can get your API key in Configuration > API Key, or in the docs.",
+          instance: '/reference/intro/authentication',
+          poem: [
+            'The ancient gatekeeper declares:',
+            "'To pass, reveal your API key.'",
+            "'bad-…', you start to ramble",
+            'Oops, you remembered it poorly!',
+          ],
+        });
+
+      const result = await run(['__tests__/__fixtures__/docs/new-docs/new-doc.md', '--key', 'bad-api-key']);
+
+      expect(result).toMatchSnapshot();
+      expect(fs.writeFileSync).not.toHaveBeenCalled();
+
+      mock.done();
+    });
+  });
 });

src/lib/syncPagePath.ts

@@ -1,5 +1,5 @@
 import type { PageMetadata } from './readPage.js';
-import type { GuidesRequestRepresentation } from './types/index.js';
+import type { GuidesRequestRepresentation, ProjectRepresentation } from './types/index.js';
 import type DocsUploadCommand from '../commands/docs/upload.js';
 
 import fs from 'node:fs/promises';
@@ -197,7 +197,7 @@ function sortFiles(files: PageMetadata<PageRepresentation>[]): PageMetadata<Page
  */
 export default async function syncPagePath(this: CommandsThatSyncMarkdown) {
   const { path: pathInput }: { path: string } = this.args;
-  const { 'dry-run': dryRun, 'skip-validation': skipValidation } = this.flags;
+  const { key, 'dry-run': dryRun, 'skip-validation': skipValidation } = this.flags;
 
   const allowedFileExtensions = ['.markdown', '.md'];
 
@@ -208,6 +208,23 @@ export default async function syncPagePath(this: CommandsThatSyncMarkdown) {
     throw err;
   });
 
+  // check whether or not the project has bidirection syncing enabled
+  // if it is, validations must be skipped to prevent frontmatter from being overwritten
+  const headers = new Headers({ authorization: `Bearer ${key}` });
+  const projectMetadata: ProjectRepresentation = await this.readmeAPIFetch('/projects/me', {
+    method: 'GET',
+    headers,
+  }).then(res => {
+    return this.handleAPIRes(res);
+  });
+
+  const biDiConnection = projectMetadata?.data?.git?.connection?.status === 'active';
+  if (biDiConnection && !skipValidation) {
+    throw new Error(
+      "Bi-directional syncing is enabled for this project. Uploading these docs will overwrite what's currently synced from Git. To proceed with the upload, re-run this command with the `--skip-validation` flag.",
+    );
+  }
+
   if (skipValidation) {
     this.warn('Skipping pre-upload validation of the Markdown file(s). This is not recommended.');
   }

src/lib/types/index.ts

@@ -13,6 +13,8 @@ export const parentUriRegexPattern =
 type guidesRequestBodySchema =
   (typeof readmeAPIv2Oas)['paths']['/versions/{version}/guides/{slug}']['patch']['requestBody']['content']['application/json']['schema'];
 
+type projectSchema =
+  (typeof readmeAPIv2Oas)['paths']['/projects/me']['get']['responses']['200']['content']['application/json']['schema'];
 /**
  * Derived from our API documentation, this is the schema for the `guides` object
  * as we send it to the ReadMe API.
@@ -24,3 +26,5 @@ export type GuidesRequestRepresentation = FromSchema<
   guidesRequestBodySchema,
   { keepDefaultedPropertiesOptional: true }
 >;
+
+export type ProjectRepresentation = FromSchema<projectSchema, { keepDefaultedPropertiesOptional: true }>;

src/lib/types/openapiDoc.ts

@@ -3245,6 +3245,21 @@ const document = {
                           description:
                             'The description of your project. This is used in the page meta description and is seen by search engines and sites like Facebook.',
                         },
+                        git: {
+                          type: 'object',
+                          properties: {
+                            connection: {
+                              type: 'object',
+                              properties: {
+                                status: {
+                                  type: 'string',
+                                  enum: ['active', 'inactive', 'none'],
+                                  default: 'none',
+                                },
+                              },
+                            },
+                          },
+                        },
                         glossary: {
                           type: 'array',
                           items: {