@gadgetinc/ggt 0.1.15 → 0.1.17

package/README.md

@@ -129,7 +129,7 @@ EXAMPLES
   Goodbye!
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/gadget-inc/ggt/blob/v0.1.15/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/gadget-inc/ggt/blob/v0.1.17/src/commands/sync.ts)_
 
 ### `ggt help [COMMAND]`
 
@@ -143,7 +143,7 @@ ARGUMENTS
   COMMAND  The command to show help for.
 ```
 
-_See code: [src/commands/help.ts](https://github.com/gadget-inc/ggt/blob/v0.1.15/src/commands/help.ts)_
+_See code: [src/commands/help.ts](https://github.com/gadget-inc/ggt/blob/v0.1.17/src/commands/help.ts)_
 
 ### `ggt list`
 
@@ -170,7 +170,7 @@ EXAMPLES
   $ ggt list --sort=slug
 ```
 
-_See code: [src/commands/list.ts](https://github.com/gadget-inc/ggt/blob/v0.1.15/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/gadget-inc/ggt/blob/v0.1.17/src/commands/list.ts)_
 
 ### `ggt login`
 
@@ -189,7 +189,7 @@ EXAMPLES
   Hello, Jane Doe (jane@example.com)
 ```
 
-_See code: [src/commands/login.ts](https://github.com/gadget-inc/ggt/blob/v0.1.15/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/gadget-inc/ggt/blob/v0.1.17/src/commands/login.ts)_
 
 ### `ggt logout`
 
@@ -204,7 +204,7 @@ EXAMPLES
   Goodbye
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/gadget-inc/ggt/blob/v0.1.15/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/gadget-inc/ggt/blob/v0.1.17/src/commands/logout.ts)_
 
 ### `ggt whoami`
 
@@ -219,7 +219,7 @@ EXAMPLES
   You are logged in as Jane Doe (jane@example.com)
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/gadget-inc/ggt/blob/v0.1.15/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/gadget-inc/ggt/blob/v0.1.17/src/commands/whoami.ts)_
 
 <!-- commandsstop -->
 

package/lib/commands/help.d.ts

@@ -1,10 +1,10 @@
-import { Command } from "@oclif/core";
+import { BaseCommand } from "../utils/base-command";
 /**
  * Copied from @oclif/plugin-help. Uses our own {@link Help} template class instead of the one from @oclif/core.
  *
  * @see https://github.com/oclif/plugin-help/blob/67b580570257b45e92d3a04d50bf2a432c59afe3/src/commands/help.ts
  */
-export default class HelpCommand extends Command {
+export default class HelpCommand extends BaseCommand<typeof HelpCommand> {
     static strict: boolean;
     static summary: string;
     static args: {

package/lib/commands/help.js

@@ -3,12 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const core_1 = require("@oclif/core");
 const help_1 = tslib_1.__importDefault(require("../utils/help"));
+const base_command_1 = require("../utils/base-command");
 /**
  * Copied from @oclif/plugin-help. Uses our own {@link Help} template class instead of the one from @oclif/core.
  *
  * @see https://github.com/oclif/plugin-help/blob/67b580570257b45e92d3a04d50bf2a432c59afe3/src/commands/help.ts
  */
-class HelpCommand extends core_1.Command {
+class HelpCommand extends base_command_1.BaseCommand {
     async run() {
         const { argv } = await this.parse();
         const help = new help_1.default(this.config, { all: true });

package/lib/commands/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"/","sources":["commands/help.ts"],"names":[],"mappings":";;;AAAA,sCAA4C;AAC5C,iEAAiC;AAEjC;;;;GAIG;AACH,MAAqB,WAAY,SAAQ,cAAO;IAY9C,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,cAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAgB,CAAC,CAAC;IACxC,CAAC;;AAfe;;;;WAAS,KAAK;GAAC;AAEf;;;;WAAU,uBAAuB;GAAC;AAElC;;;;WAAO;QACrB,OAAO,EAAE,WAAI,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,+BAA+B;SAC7C,CAAC;KACH;GAAC;kBAViB,WAAW","sourcesContent":["import { Args, Command } from \"@oclif/core\";\nimport Help from \"../utils/help\";\n\n/**\n * Copied from @oclif/plugin-help. Uses our own {@link Help} template class instead of the one from @oclif/core.\n *\n * @see https://github.com/oclif/plugin-help/blob/67b580570257b45e92d3a04d50bf2a432c59afe3/src/commands/help.ts\n */\nexport default class HelpCommand extends Command {\n  static override strict = false;\n\n  static override summary = \"Display help for ggt.\";\n\n  static override args = {\n    command: Args.string({\n      required: false,\n      description: \"The command to show help for.\",\n    }),\n  };\n\n  async run(): Promise<void> {\n    const { argv } = await this.parse();\n    const help = new Help(this.config, { all: true });\n    await help.showHelp(argv as string[]);\n  }\n}\n"]}
+{"version":3,"file":"help.js","sourceRoot":"/","sources":["commands/help.ts"],"names":[],"mappings":";;;AAAA,sCAAmC;AACnC,iEAAiC;AACjC,wDAAoD;AAEpD;;;;GAIG;AACH,MAAqB,WAAY,SAAQ,0BAA+B;IAYtE,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,cAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAgB,CAAC,CAAC;IACxC,CAAC;;AAfe;;;;WAAS,KAAK;GAAC;AAEf;;;;WAAU,uBAAuB;GAAC;AAElC;;;;WAAO;QACrB,OAAO,EAAE,WAAI,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,+BAA+B;SAC7C,CAAC;KACH;GAAC;kBAViB,WAAW","sourcesContent":["import { Args } from \"@oclif/core\";\nimport Help from \"../utils/help\";\nimport { BaseCommand } from \"../utils/base-command\";\n\n/**\n * Copied from @oclif/plugin-help. Uses our own {@link Help} template class instead of the one from @oclif/core.\n *\n * @see https://github.com/oclif/plugin-help/blob/67b580570257b45e92d3a04d50bf2a432c59afe3/src/commands/help.ts\n */\nexport default class HelpCommand extends BaseCommand<typeof HelpCommand> {\n  static override strict = false;\n\n  static override summary = \"Display help for ggt.\";\n\n  static override args = {\n    command: Args.string({\n      required: false,\n      description: \"The command to show help for.\",\n    }),\n  };\n\n  async run(): Promise<void> {\n    const { argv } = await this.parse();\n    const help = new Help(this.config, { all: true });\n    await help.showHelp(argv as string[]);\n  }\n}\n"]}

package/lib/commands/list.d.ts

@@ -13,5 +13,6 @@ export default class List extends BaseCommand<typeof List> {
         'no-truncate': import("@oclif/core/lib/interfaces").Flag<boolean>;
         'no-header': import("@oclif/core/lib/interfaces").Flag<boolean>;
     };
+    requireUser: boolean;
     run(): Promise<void>;
 }

package/lib/commands/list.js

@@ -7,15 +7,24 @@ const ts_dedent_1 = tslib_1.__importDefault(require("ts-dedent"));
 const base_command_1 = require("../utils/base-command");
 const context_1 = require("../utils/context");
 class List extends base_command_1.BaseCommand {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "requireUser", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: true
+        });
+    }
     async run() {
         const { flags } = await this.parse(List);
-        const user = await context_1.context.getUser();
-        if (!user) {
-            this.error("You are not logged in -- no apps available", { exit: 1 });
-        }
         const apps = await context_1.context.getAvailableApps();
-        if (apps.length === 0 && !flags.csv) {
-            this.log("No apps found");
+        if (!apps.length) {
+            this.log((0, ts_dedent_1.default) `
+          It doesn't look like you have any applications.
+
+          Visit https://gadget.new to create one!
+      `);
             return;
         }
         core_1.ux.table(apps, {

package/lib/commands/list.js.map

@@ -1 +1 @@
-{"version":3,"file":"list.js","sourceRoot":"/","sources":["commands/list.ts"],"names":[],"mappings":";;;AAAA,0DAA0B;AAC1B,sCAAiC;AACjC,kEAA+B;AAC/B,wDAAoD;AAEpD,8CAA2C;AAE3C,MAAqB,IAAK,SAAQ,0BAAwB;IAiBxD,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,iBAAO,CAAC,OAAO,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,EAAE;YACT,IAAI,CAAC,KAAK,CAAC,4CAA4C,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;SACvE;QACD,MAAM,IAAI,GAAG,MAAM,iBAAO,CAAC,gBAAgB,EAAE,CAAC;QAE9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACnC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YAC1B,OAAO;SACR;QAED,SAAE,CAAC,KAAK,CACN,IAAkD,EAClD;YACE,EAAE,EAAE;gBACF,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE,IAAI;aACf;YACD,IAAI,EAAE;gBACJ,MAAM,EAAE,MAAM;aACf;YACD,aAAa,EAAE;gBACb,MAAM,EAAE,QAAQ;aACjB;SACF,EACD;YACE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9B,GAAG,KAAK,EAAE,eAAe;SAC1B,CACF,CAAC;IACJ,CAAC;;AAhDe;;;;WAAU,0DAA0D;GAAC;AAErE;;;;WAAQ,MAAM;GAAC;AAEf;;;;WAAW;QACzB,IAAA,mBAAM,EAAC,IAAA,eAAK,EAAA;;;;KAIX,CAAC;KACH;GAAC;AAEc;;;;WAAQ;QACtB,GAAG,SAAE,CAAC,KAAK,CAAC,KAAK,EAAE;KACpB;GAAC;kBAfiB,IAAI","sourcesContent":["import chalk from \"chalk\";\nimport { ux } from \"@oclif/core\";\nimport dedent from \"ts-dedent\";\nimport { BaseCommand } from \"../utils/base-command\";\nimport type { App } from \"../utils/context\";\nimport { context } from \"../utils/context\";\n\nexport default class List extends BaseCommand<typeof List> {\n  static override summary = \"List the apps available to the currently logged in user.\";\n\n  static override usage = \"list\";\n\n  static override examples = [\n    dedent(chalk`\n      {gray $ ggt list}\n      {gray $ ggt list --extended}\n      {gray $ ggt list --sort=slug}\n    `),\n  ];\n\n  static override flags = {\n    ...ux.table.flags(),\n  };\n\n  async run(): Promise<void> {\n    const { flags } = await this.parse(List);\n    const user = await context.getUser();\n    if (!user) {\n      this.error(\"You are not logged in -- no apps available\", { exit: 1 });\n    }\n    const apps = await context.getAvailableApps();\n\n    if (apps.length === 0 && !flags.csv) {\n      this.log(\"No apps found\");\n      return;\n    }\n\n    ux.table<App & Record<string, never>>(\n      apps as unknown as (App & Record<string, never>)[],\n      {\n        id: {\n          header: \"ID\",\n          extended: true,\n        },\n        slug: {\n          header: \"Slug\",\n        },\n        primaryDomain: {\n          header: \"Domain\",\n        },\n      },\n      {\n        printLine: this.log.bind(this),\n        ...flags, // parsed flags\n      }\n    );\n  }\n}\n"]}
+{"version":3,"file":"list.js","sourceRoot":"/","sources":["commands/list.ts"],"names":[],"mappings":";;;AAAA,0DAA0B;AAC1B,sCAAiC;AACjC,kEAA+B;AAC/B,wDAAoD;AAEpD,8CAA2C;AAE3C,MAAqB,IAAK,SAAQ,0BAAwB;IAA1D;;QAiBW;;;;mBAAc,IAAI;WAAC;IAmC9B,CAAC;IAjCC,KAAK,CAAC,GAAG;QACP,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEzC,MAAM,IAAI,GAAG,MAAM,iBAAO,CAAC,gBAAgB,EAAE,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAChB,IAAI,CAAC,GAAG,CAAC,IAAA,mBAAM,EAAA;;;;OAId,CAAC,CAAC;YACH,OAAO;SACR;QAED,SAAE,CAAC,KAAK,CACN,IAAkD,EAClD;YACE,EAAE,EAAE;gBACF,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE,IAAI;aACf;YACD,IAAI,EAAE;gBACJ,MAAM,EAAE,MAAM;aACf;YACD,aAAa,EAAE;gBACb,MAAM,EAAE,QAAQ;aACjB;SACF,EACD;YACE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9B,GAAG,KAAK,EAAE,eAAe;SAC1B,CACF,CAAC;IACJ,CAAC;;AAlDe;;;;WAAU,0DAA0D;EAA7D,CAA8D;AAErE;;;;WAAQ,MAAM;EAAT,CAAU;AAEf;;;;WAAW;QACzB,IAAA,mBAAM,EAAC,IAAA,eAAK,EAAA;;;;KAIX,CAAC;KACH;EANuB,CAMtB;AAEc;;;;WAAQ;QACtB,GAAG,SAAE,CAAC,KAAK,CAAC,KAAK,EAAE;KACpB;EAFoB,CAEnB;kBAfiB,IAAI","sourcesContent":["import chalk from \"chalk\";\nimport { ux } from \"@oclif/core\";\nimport dedent from \"ts-dedent\";\nimport { BaseCommand } from \"../utils/base-command\";\nimport type { App } from \"../utils/context\";\nimport { context } from \"../utils/context\";\n\nexport default class List extends BaseCommand<typeof List> {\n  static override summary = \"List the apps available to the currently logged in user.\";\n\n  static override usage = \"list\";\n\n  static override examples = [\n    dedent(chalk`\n      {gray $ ggt list}\n      {gray $ ggt list --extended}\n      {gray $ ggt list --sort=slug}\n    `),\n  ];\n\n  static override flags = {\n    ...ux.table.flags(),\n  };\n\n  override requireUser = true;\n\n  async run(): Promise<void> {\n    const { flags } = await this.parse(List);\n\n    const apps = await context.getAvailableApps();\n    if (!apps.length) {\n      this.log(dedent`\n          It doesn't look like you have any applications.\n\n          Visit https://gadget.new to create one!\n      `);\n      return;\n    }\n\n    ux.table<App & Record<string, never>>(\n      apps as unknown as (App & Record<string, never>)[],\n      {\n        id: {\n          header: \"ID\",\n          extended: true,\n        },\n        slug: {\n          header: \"Slug\",\n        },\n        primaryDomain: {\n          header: \"Domain\",\n        },\n      },\n      {\n        printLine: this.log.bind(this),\n        ...flags, // parsed flags\n      }\n    );\n  }\n}\n"]}

package/lib/commands/sync.d.ts

@@ -4,7 +4,7 @@ import PQueue from "p-queue";
 import { BaseCommand } from "../utils/base-command";
 import type { Query } from "../utils/client";
 import { Client } from "../utils/client";
-import { Ignorer } from "../utils/fs-utils";
+import { FSIgnorer } from "../utils/fs-utils";
 import type { PublishFileSyncEventsMutation, PublishFileSyncEventsMutationVariables, RemoteFilesVersionQuery, RemoteFilesVersionQueryVariables, RemoteFileSyncEventsSubscription, RemoteFileSyncEventsSubscriptionVariables } from "../__generated__/graphql";
 export default class Sync extends BaseCommand<typeof Sync> {
     static priority: number;
@@ -23,29 +23,104 @@ export default class Sync extends BaseCommand<typeof Sync> {
     };
     static examples: string[];
     requireUser: boolean;
+    /**
+     * The current status of the sync process.
+     */
     status: SyncStatus;
+    /**
+     * The absolute path to the directory to sync files to.
+     */
     dir: string;
-    recentWrites: Set<unknown>;
+    /**
+     * A list of filepaths that have changed because of a remote file-sync event. This is used to avoid sending files that
+     * we recently received from a remote file-sync event.
+     */
+    recentRemoteChanges: Set<unknown>;
+    /**
+     * A FIFO async callback queue that ensures we process file-sync events in the order they occurred.
+     */
     queue: PQueue<import("p-queue/dist/priority-queue").default, import("p-queue").DefaultAddOptions>;
+    /**
+     * A GraphQL client connected to the app's /edit/api/graphql-ws endpoint
+     */
     client: Client;
-    ignorer: Ignorer;
+    /**
+     * Loads the .ignore file and provides methods for checking if a file should be ignored.
+     */
+    ignorer: FSIgnorer;
+    /**
+     * Watches the local filesystem for changes.
+     */
     watcher: FSWatcher;
+    /**
+     * Holds information about the state of the local filesystem. It's persisted to `.gadget/sync.json`.
+     */
     metadata: {
+        /**
+         * The app this filesystem is synced to.
+         */
         app: string;
+        /**
+         * The last filesVersion that was successfully written to the filesystem. This is used to determine if the remote
+         * filesystem is ahead of the local one.
+         */
         filesVersion: string;
+        /**
+         * The largest mtime that was seen on the local filesystem before `ggt sync` stopped. This is used to determine if
+         * the local filesystem has changed since the last sync.
+         *
+         * Note: This does not include the mtime of files that are ignored.
+         */
         mtime: number;
     };
+    /**
+     * A debounced function that enqueue's local file changes to be sent to Gadget.
+     */
     publish: DebouncedFunc<() => void>;
+    /**
+     * Gracefully stops the sync.
+     */
     stop: (error?: unknown) => Promise<void>;
-    finished: Promise<void>;
-    markFinished: () => void;
+    /**
+     * Turns an absolute filepath into a relative one from {@linkcode dir}.
+     */
     relative(to: string): string;
+    /**
+     * Combines path segments into an absolute filepath that starts at {@linkcode dir}.
+     */
     absolute(...pathSegments: string[]): string;
+    /**
+     * Similar to {@linkcode relative} in that it turns a filepath into a relative one from {@linkcode dir}. However, it
+     * also changes any slashes to be posix/unix-like forward slashes, condenses repeat slashes into a single slash.
+     *
+     * This is used when sending file-sync events to Gadget to ensure that the paths are consistent across platforms.
+     *
+     * @see https://www.npmjs.com/package/normalize-path
+     */
     normalize(filepath: string, isDirectory?: boolean): string;
+    /**
+     * Pretty-prints changed and deleted filepaths to the console.
+     *
+     * @param prefix The prefix to print before each line.
+     * @param changed The filepaths that have changed.
+     * @param deleted The filepaths that have been deleted.
+     * @param options.limit The maximum number of lines to print. Defaults to 10. If debug is enabled, this is ignored.
+     */
     logPaths(prefix: string, changed: string[], deleted: string[], { limit }?: {
         limit?: number | undefined;
     }): void;
+    /**
+     * Initializes the sync process.
+     * - Ensures the directory exists.
+     * - Ensures the directory is empty or contains a `.gadget/sync.json` file.
+     * - Ensures an app is selected and that it matches the app the directory was previously synced to.
+     * - Ensures yarn v1 is installed.
+     * - Prompts the user how to resolve conflicts if the local filesystem has changed since the last sync.
+     */
     init(): Promise<void>;
+    /**
+     * Runs the sync process until it is stopped or an error occurs.
+     */
     run(): Promise<void>;
 }
 export declare enum SyncStatus {

package/lib/commands/sync.js

@@ -12,7 +12,6 @@ const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const inquirer_1 = require("inquirer");
 const lodash_1 = require("lodash");
 const lodash_2 = require("lodash");
-const lodash_3 = require("lodash");
 const normalize_path_1 = tslib_1.__importDefault(require("normalize-path"));
 const p_map_1 = tslib_1.__importDefault(require("p-map"));
 const p_queue_1 = tslib_1.__importDefault(require("p-queue"));
@@ -27,6 +26,7 @@ const errors_1 = require("../utils/errors");
 const flags_1 = require("../utils/flags");
 const fs_utils_1 = require("../utils/fs-utils");
 const graphql_1 = require("../__generated__/graphql");
+const promise_1 = require("../utils/promise");
 class Sync extends base_command_1.BaseCommand {
     constructor() {
         super(...arguments);
@@ -36,92 +36,146 @@ class Sync extends base_command_1.BaseCommand {
             writable: true,
             value: true
         });
+        /**
+         * The current status of the sync process.
+         */
         Object.defineProperty(this, "status", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: SyncStatus.STARTING
         });
+        /**
+         * The absolute path to the directory to sync files to.
+         */
         Object.defineProperty(this, "dir", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "recentWrites", {
+        /**
+         * A list of filepaths that have changed because of a remote file-sync event. This is used to avoid sending files that
+         * we recently received from a remote file-sync event.
+         */
+        Object.defineProperty(this, "recentRemoteChanges", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new Set()
         });
+        /**
+         * A FIFO async callback queue that ensures we process file-sync events in the order they occurred.
+         */
         Object.defineProperty(this, "queue", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new p_queue_1.default({ concurrency: 1 })
         });
+        /**
+         * A GraphQL client connected to the app's /edit/api/graphql-ws endpoint
+         */
         Object.defineProperty(this, "client", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Loads the .ignore file and provides methods for checking if a file should be ignored.
+         */
         Object.defineProperty(this, "ignorer", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Watches the local filesystem for changes.
+         */
         Object.defineProperty(this, "watcher", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Holds information about the state of the local filesystem. It's persisted to `.gadget/sync.json`.
+         */
         Object.defineProperty(this, "metadata", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: {
+                /**
+                 * The app this filesystem is synced to.
+                 */
                 app: "",
+                /**
+                 * The last filesVersion that was successfully written to the filesystem. This is used to determine if the remote
+                 * filesystem is ahead of the local one.
+                 */
                 filesVersion: "0",
+                /**
+                 * The largest mtime that was seen on the local filesystem before `ggt sync` stopped. This is used to determine if
+                 * the local filesystem has changed since the last sync.
+                 *
+                 * Note: This does not include the mtime of files that are ignored.
+                 */
                 mtime: 0,
             }
         });
+        /**
+         * A debounced function that enqueue's local file changes to be sent to Gadget.
+         */
         Object.defineProperty(this, "publish", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Gracefully stops the sync.
+         */
         Object.defineProperty(this, "stop", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "finished", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "markFinished", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
     }
+    /**
+     * Turns an absolute filepath into a relative one from {@linkcode dir}.
+     */
     relative(to) {
         return path_1.default.relative(this.dir, to);
     }
+    /**
+     * Combines path segments into an absolute filepath that starts at {@linkcode dir}.
+     */
     absolute(...pathSegments) {
         return path_1.default.resolve(this.dir, ...pathSegments);
     }
+    /**
+     * Similar to {@linkcode relative} in that it turns a filepath into a relative one from {@linkcode dir}. However, it
+     * also changes any slashes to be posix/unix-like forward slashes, condenses repeat slashes into a single slash.
+     *
+     * This is used when sending file-sync events to Gadget to ensure that the paths are consistent across platforms.
+     *
+     * @see https://www.npmjs.com/package/normalize-path
+     */
     normalize(filepath, isDirectory = false) {
-        return (0, normalize_path_1.default)(`${path_1.default.isAbsolute(filepath) ? this.relative(filepath) : filepath}${isDirectory ? "/" : ""}`, false);
+        return (0, normalize_path_1.default)(path_1.default.isAbsolute(filepath) ? this.relative(filepath) : filepath) + (isDirectory ? "/" : "");
     }
+    /**
+     * Pretty-prints changed and deleted filepaths to the console.
+     *
+     * @param prefix The prefix to print before each line.
+     * @param changed The filepaths that have changed.
+     * @param deleted The filepaths that have been deleted.
+     * @param options.limit The maximum number of lines to print. Defaults to 10. If debug is enabled, this is ignored.
+     */
     logPaths(prefix, changed, deleted, { limit = 10 } = {}) {
         const lines = (0, lodash_1.sortBy)([
             ...changed.map((filepath) => (0, chalk_1.default) `{green ${prefix}} ${this.normalize(filepath)} {gray (changed)}`),
@@ -139,9 +193,16 @@ class Sync extends base_command_1.BaseCommand {
         this.log((0, chalk_1.default) `{gray ${(0, pluralize_1.default)("file", lines.length, true)} in total. ${changed.length} changed, ${deleted.length} deleted.}`);
         this.log();
     }
+    /**
+     * Initializes the sync process.
+     * - Ensures the directory exists.
+     * - Ensures the directory is empty or contains a `.gadget/sync.json` file.
+     * - Ensures an app is selected and that it matches the app the directory was previously synced to.
+     * - Ensures yarn v1 is installed.
+     * - Prompts the user how to resolve conflicts if the local filesystem has changed since the last sync.
+     */
     async init() {
         await super.init();
-        (0, assert_1.default)((0, lodash_2.isString)(this.args["directory"]));
         this.dir =
             this.config.windows && this.args["directory"].startsWith("~/")
                 ? path_1.default.join(this.config.home, this.args["directory"].slice(2))
@@ -182,7 +243,7 @@ class Sync extends base_command_1.BaseCommand {
         await context_1.context.setApp(this.metadata.app);
         this.client = new client_1.Client();
         // local files/folders that should never be published
-        this.ignorer = new fs_utils_1.Ignorer(this.dir, ["node_modules", ".gadget", ".git"]);
+        this.ignorer = new fs_utils_1.FSIgnorer(this.dir, ["node_modules", ".gadget", ".git"]);
         this.watcher = new chokidar_1.FSWatcher({
             ignored: (filepath) => this.ignorer.ignores(filepath),
             // don't emit an event for every watched file on boot
@@ -207,6 +268,8 @@ class Sync extends base_command_1.BaseCommand {
                     files.set(this.absolute(filepath), stats);
                 }
             }
+            // never include the root directory
+            files.delete(this.dir);
             return files;
         };
         const changedFiles = await getChangedFiles();
@@ -230,7 +293,9 @@ class Sync extends base_command_1.BaseCommand {
             case Action.MERGE: {
                 // get all the changed files again in case more changed
                 const files = await getChangedFiles();
-                // we purposefully don't set the returned remoteFilesVersion here because we haven't processed the in-between versions yet
+                // We purposefully don't set the returned remoteFilesVersion here because we haven't received the remote changes
+                // yet. This will cause us to receive the local files that we just published + the remote files that were
+                // changed since the last sync.
                 await this.client.queryUnwrap({
                     query: exports.PUBLISH_FILE_SYNC_EVENTS_MUTATION,
                     variables: {
@@ -240,10 +305,11 @@ class Sync extends base_command_1.BaseCommand {
                                 if (stats.mtime.getTime() > this.metadata.mtime) {
                                     this.metadata.mtime = stats.mtime.getTime();
                                 }
+                                const isDirectory = stats.isDirectory();
                                 return {
-                                    path: this.normalize(filepath),
+                                    path: this.normalize(filepath, isDirectory),
                                     mode: stats.mode,
-                                    content: await fs_extra_1.default.readFile(filepath, "base64"),
+                                    content: isDirectory ? "" : await fs_extra_1.default.readFile(filepath, "base64"),
                                     encoding: graphql_1.FileSyncEncoding.Base64,
                                 };
                             }),
@@ -254,6 +320,8 @@ class Sync extends base_command_1.BaseCommand {
                 break;
             }
             case Action.RESET: {
+                // delete all the local files that have changed since the last sync and set the files version to 0 so we receive
+                // all the remote files again, including any files that we just deleted that still exist
                 await (0, p_map_1.default)(changedFiles, ([filepath]) => fs_extra_1.default.remove(filepath));
                 this.metadata.filesVersion = "0";
                 break;
@@ -264,11 +332,12 @@ class Sync extends base_command_1.BaseCommand {
         }
         this.debug("started");
     }
+    /**
+     * Runs the sync process until it is stopped or an error occurs.
+     */
     async run() {
         let error;
-        this.finished = new Promise((resolve) => {
-            this.markFinished = resolve;
-        });
+        const stopped = new promise_1.PromiseSignal();
         this.stop = async (e) => {
             if (this.status != SyncStatus.RUNNING)
                 return;
@@ -286,7 +355,7 @@ class Sync extends base_command_1.BaseCommand {
                 await Promise.allSettled([this.watcher.close(), this.client.dispose()]);
                 this.debug("stopped");
                 this.status = SyncStatus.STOPPED;
-                this.markFinished();
+                stopped.resolve();
             }
         };
         for (const signal of ["SIGINT", "SIGTERM"]) {
@@ -331,10 +400,10 @@ class Sync extends base_command_1.BaseCommand {
                             return;
                         }
                         const filepath = this.absolute(file.path);
-                        this.recentWrites.add(filepath);
+                        this.recentRemoteChanges.add(filepath);
                         if ("content" in file) {
                             if (!file.path.endsWith("/")) {
-                                this.recentWrites.add(path_1.default.dirname(filepath));
+                                this.recentRemoteChanges.add(path_1.default.dirname(filepath));
                                 await fs_extra_1.default.ensureDir(path_1.default.dirname(filepath), { mode: 0o755 });
                                 await fs_extra_1.default.writeFile(filepath, Buffer.from(file.content, file.encoding ?? graphql_1.FileSyncEncoding.Utf8), {
                                     mode: file.mode,
@@ -367,7 +436,7 @@ class Sync extends base_command_1.BaseCommand {
             },
         });
         const localFilesBuffer = new Map();
-        this.publish = (0, lodash_3.debounce)(() => {
+        this.publish = (0, lodash_2.debounce)(() => {
             const localFiles = new Map(localFilesBuffer.entries());
             localFilesBuffer.clear();
             void this.queue
@@ -388,8 +457,8 @@ class Sync extends base_command_1.BaseCommand {
                             });
                         }
                         catch (error) {
-                            // A file could have been changed and then deleted before we process the change event, so the readFile above will raise
-                            // an ENOENT. This is normal operation, so just ignore this event.
+                            // A file could have been changed and then deleted before we process the change event, so the readFile
+                            // above will raise an ENOENT. This is normal operation, so just ignore this event.
                             (0, fs_utils_1.ignoreEnoent)(error);
                         }
                     }
@@ -427,12 +496,13 @@ class Sync extends base_command_1.BaseCommand {
                 this.debug("skipping event caused by ignored file %s", relativePath);
                 return;
             }
-            // we only update the mtime if the file is not ignored, because if we restart and the mtime is set to an ignored file, then it could
-            // be greater than the mtime of all non ignored files and we'll think that local files have changed when only an ignored one has
+            // we only update the mtime if the file is not ignored, because if we restart and the mtime is set to an ignored
+            // file, then it could be greater than the mtime of all non ignored files and we'll think that local files have
+            // changed when only an ignored one has
             if (stats && stats.mtime.getTime() > this.metadata.mtime) {
                 this.metadata.mtime = stats.mtime.getTime();
             }
-            if (this.recentWrites.delete(filepath)) {
+            if (this.recentRemoteChanges.delete(filepath)) {
                 this.debug("skipping event caused by recent write %s", relativePath);
                 return;
             }
@@ -476,7 +546,7 @@ class Sync extends base_command_1.BaseCommand {
       Watching for file changes... {gray Press Ctrl+C to stop}
     `));
         this.log();
-        await this.finished;
+        await stopped;
         if (error) {
             this.notify({ subtitle: "Uh oh!", message: "An error occurred while syncing files" });
             throw error;