feat: introduce knock init and knock.json file

Author: cjbell

src/commands/guide/push.ts

@@ -53,6 +53,7 @@ export default class GuidePush extends BaseCommand<typeof GuidePush> {
     const target = await Guide.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [guides, readErrors] = await Guide.readAllForCommandTarget(target, {

src/commands/guide/validate.ts

@@ -41,6 +41,7 @@ export default class GuideValidate extends BaseCommand<typeof GuideValidate> {
     const target = await Guide.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [guides, readErrors] = await Guide.readAllForCommandTarget(target, {

src/commands/init.ts

@@ -0,0 +1,73 @@
+import * as path from "node:path";
+
+import enquirer from "enquirer";
+import * as fs from "fs-extra";
+
+import BaseCommand from "@/lib/base-command";
+
+export default class Init extends BaseCommand<typeof Init> {
+  protected requiresAuth = false;
+
+  static summary =
+    "Initialize a new Knock project with a knock.json configuration file.";
+
+  static description =
+    "Creates a knock.json configuration file in the current directory " +
+    "to store project-level settings like the knock resources directory.";
+
+  public async run(): Promise<void> {
+    const configPath = path.resolve(process.cwd(), "knock.json");
+
+    // 1. Check if knock.json already exists
+    const configExists = await fs.pathExists(configPath);
+    if (configExists) {
+      this.error(
+        "A knock.json file already exists in this directory. Aborting.",
+      );
+    }
+
+    // 2. Prompt user for the knock directory location
+    const { knockDir } = await enquirer.prompt<{ knockDir: string }>({
+      type: "input",
+      name: "knockDir",
+      message: "Where do you want to store your Knock resources?",
+      initial: ".knock",
+    });
+
+    // 3. Create the knock directory and resource subdirectories
+    const knockDirPath = path.resolve(process.cwd(), knockDir);
+    await fs.ensureDir(knockDirPath);
+
+    // Create resource subdirectories with .gitignore files
+    const resourceDirs = [
+      "workflows",
+      "layouts",
+      "message-types",
+      "partials",
+      "guides",
+      "translations",
+    ];
+
+    for (const resourceDir of resourceDirs) {
+      const resourceDirPath = path.resolve(knockDirPath, resourceDir);
+      await fs.ensureDir(resourceDirPath);
+
+      // Create a .gitignore file in each resource directory
+      const gitignorePath = path.resolve(resourceDirPath, ".gitignore");
+      await fs.writeFile(gitignorePath, "");
+    }
+
+    // 4. Write the knock.json configuration file
+    await fs.outputJson(
+      configPath,
+      {
+        $schema: "https://schemas.knock.app/cli/knock.json",
+        knockDir,
+      },
+      { spaces: 2 },
+    );
+
+    this.log(`‣ Successfully initialized Knock project at ${process.cwd()}`);
+    this.log(`‣ Resources directory: ${knockDir}`);
+  }
+}

src/commands/layout/push.ts

@@ -59,6 +59,7 @@ export default class EmailLayoutPush extends BaseCommand<
     const target = await EmailLayout.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [layouts, readErrors] = await EmailLayout.readAllForCommandTarget(

src/commands/layout/validate.ts

@@ -47,6 +47,7 @@ export default class EmailLayoutValidate extends BaseCommand<
     const target = await EmailLayout.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [layouts, readErrors] = await EmailLayout.readAllForCommandTarget(

src/commands/message-type/push.ts

@@ -58,6 +58,7 @@ export default class MessageTypePush extends BaseCommand<
     const target = await MessageType.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
     const [messageTypes, readErrors] =
       await MessageType.readAllForCommandTarget(target, {

src/commands/message-type/validate.ts

@@ -49,6 +49,7 @@ export default class MessageTypeValidate extends BaseCommand<
     const target = await MessageType.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [messageTypes, readErrors] =

src/commands/partial/push.ts

@@ -56,6 +56,7 @@ export default class PartialPush extends BaseCommand<typeof PartialPush> {
     const target = await Partial.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [partials, readErrors] = await Partial.readAllForCommandTarget(

src/commands/partial/validate.ts

@@ -46,6 +46,7 @@ export default class PartialValidate extends BaseCommand<
     const target = await Partial.ensureValidCommandTarget(
       this.props,
       this.runContext,
+      this.projectConfig,
     );
 
     const [partials, readErrors] = await Partial.readAllForCommandTarget(

src/commands/pull.ts

@@ -1,10 +1,12 @@
 import * as path from "node:path";
 
 import { Flags } from "@oclif/core";
+import * as fs from "fs-extra";
 
 import BaseCommand from "@/lib/base-command";
 import * as CustomFlags from "@/lib/helpers/flag";
 import { DirContext } from "@/lib/helpers/fs";
+import { resolveKnockDir } from "@/lib/helpers/project-config";
 import { promptToConfirm } from "@/lib/helpers/ux";
 import {
   ALL_RESOURCE_TYPES,
@@ -31,7 +33,7 @@ export default class Pull extends BaseCommand<typeof Pull> {
     branch: CustomFlags.branch,
     "knock-dir": CustomFlags.dirPath({
       summary: "The target directory path to pull all resources into.",
-      required: true,
+      required: false,
     }),
     "hide-uncommitted-changes": Flags.boolean({
       summary: "Hide any uncommitted changes.",
@@ -43,7 +45,30 @@ export default class Pull extends BaseCommand<typeof Pull> {
 
   public async run(): Promise<void> {
     const { flags } = this.props;
-    const targetDirCtx = flags["knock-dir"];
+
+    // Resolve knock directory: flag takes precedence, otherwise use knock.json
+    const knockDirPath = resolveKnockDir(
+      flags["knock-dir"]?.abspath,
+      this.projectConfig,
+    );
+
+    if (!knockDirPath) {
+      this.error(
+        "No knock directory specified. Either provide --knock-dir flag or run `knock init` to create a knock.json configuration file.",
+      );
+    }
+
+    // Convert knockDirPath to DirContext
+    const abspath = path.isAbsolute(knockDirPath)
+      ? knockDirPath
+      : path.resolve(process.cwd(), knockDirPath);
+
+    const exists = await fs.pathExists(abspath);
+    if (exists && !(await fs.lstat(abspath)).isDirectory()) {
+      this.error(`${knockDirPath} exists but is not a directory`);
+    }
+
+    const targetDirCtx: DirContext = { abspath, exists };
 
     const prompt = targetDirCtx.exists
       ? `Pull latest resources into ${targetDirCtx.abspath}?\n  This will overwrite the contents of this directory.`