Add ability to configure custom YAML tags for VSCode.

Author: stevensJourney

cli/src/api/write-vscode-settings-for-yaml-env.ts

@@ -0,0 +1,28 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VSCODE_YAML_TAGS = ['!env scalar'];
+
+/**
+ * Writes or merges .vscode/settings.json in the workspace root so that YAML files
+ * get proper schema support for the !env custom tag.
+ */
+export function writeVscodeSettingsForYamlEnv(workspaceRoot: string): void {
+  const vscodeDir = join(workspaceRoot, '.vscode');
+  const settingsPath = join(vscodeDir, 'settings.json');
+
+  let settings: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      const raw = readFileSync(settingsPath, 'utf-8');
+      settings = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      // If invalid JSON, overwrite with our settings
+    }
+  }
+
+  const currentSettings = (settings['yaml.customTags'] ?? []) as string[];
+  settings['yaml.customTags'] = [...currentSettings, ...VSCODE_YAML_TAGS];
+  mkdirSync(vscodeDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}

cli/src/commands/init/cloud.ts

@@ -1,25 +1,30 @@
-import { ux } from '@oclif/core';
+import { Flags, ux } from '@oclif/core';
 import { cpSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { InstanceCommand, PowerSyncCommand } from '@powersync/cli-core';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { writeVscodeSettingsForYamlEnv } from '../../api/write-vscode-settings-for-yaml-env.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
 
 export default class InitCloud extends PowerSyncCommand {
   static description =
     'Copy a Cloud template into a config directory (default powersync/). Edit service.yaml then run link cloud and deploy.';
   static summary = 'Scaffold a PowerSync Cloud config directory from a template.';
   static flags = {
-    ...InstanceCommand.flags
+    ...InstanceCommand.flags,
+    vscode: Flags.boolean({
+      description: 'Configure the workspace with .vscode settings for YAML custom tags (!env).',
+      default: false
+    })
   };
 
   async run(): Promise<void> {
     const { flags } = await this.parse(InitCloud);
-    const { directory } = flags;
+    const { directory, vscode } = flags;
     const targetDir = this.resolveProjectDir(flags);
 
     if (existsSync(targetDir)) {
@@ -38,6 +43,10 @@ export default class InitCloud extends PowerSyncCommand {
     mkdirSync(targetDir, { recursive: true });
     cpSync(templatePath, targetDir, { recursive: true });
 
+    if (vscode) {
+      writeVscodeSettingsForYamlEnv(process.cwd());
+    }
+
     const instructions = [
       'Create a new instance with ',
       ux.colorize('blue', 'powersync link cloud --create'),
@@ -48,15 +57,18 @@ export default class InitCloud extends PowerSyncCommand {
       'to deploy.'
     ].join('\n');
 
-    this.log(
-      [
-        ux.colorize('green', 'Created PowerSync cloud project!'),
-        '',
-        ux.colorize('cyan', 'Configuration files are located in:'),
-        ux.colorize('gray', targetDir),
-        '',
-        ux.colorize('yellow', instructions)
-      ].join('\n')
-    );
+    const lines = [
+      ux.colorize('green', 'Created PowerSync cloud project!'),
+      '',
+      ux.colorize('cyan', 'Configuration files are located in:'),
+      ux.colorize('gray', targetDir),
+      '',
+      ux.colorize('yellow', instructions)
+    ];
+    if (vscode) {
+      lines.splice(5, 0, ux.colorize('gray', 'Added .vscode/settings.json for YAML !env tag support.'));
+      lines.splice(6, 0, '');
+    }
+    this.log(lines.join('\n'));
   }
 }

cli/src/commands/init/self-hosted.ts

@@ -1,25 +1,30 @@
-import { ux } from '@oclif/core';
+import { Flags, ux } from '@oclif/core';
 import { cpSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { InstanceCommand, PowerSyncCommand, SERVICE_FILENAME } from '@powersync/cli-core';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { writeVscodeSettingsForYamlEnv } from '../../api/write-vscode-settings-for-yaml-env.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
 
 export default class InitSelfHosted extends PowerSyncCommand {
   static description =
     'Copy a self-hosted template into a config directory (default powersync/). Configure service.yaml with your self-hosted instance details.';
   static summary = 'Scaffold a PowerSync self-hosted config directory from a template.';
   static flags = {
-    ...InstanceCommand.flags
+    ...InstanceCommand.flags,
+    vscode: Flags.boolean({
+      description: 'Configure the workspace with .vscode settings for YAML custom tags (!env).',
+      default: false
+    })
   };
 
   async run(): Promise<void> {
     const { flags } = await this.parse(InitSelfHosted);
-    const { directory } = flags;
+    const { directory, vscode } = flags;
     const targetDir = this.resolveProjectDir(flags);
 
     if (existsSync(targetDir)) {
@@ -38,22 +43,29 @@ export default class InitSelfHosted extends PowerSyncCommand {
     mkdirSync(targetDir, { recursive: true });
     cpSync(templatePath, targetDir, { recursive: true });
 
+    if (vscode) {
+      writeVscodeSettingsForYamlEnv(process.cwd());
+    }
+
     const instructions = [
       'Self Hosted projects currently require external configuration for starting and deploying.',
       `Configure the ${SERVICE_FILENAME} file with your self-hosted instance details.`,
       `See the Docker topic, with ${ux.colorize('blue', 'powersync docker --help')} for local development services.`,
       'Please refer to the PowerSync Self-Hosted documentation for more information.'
     ].join('\n');
 
-    this.log(
-      [
-        ux.colorize('green', 'Created PowerSync self-hosted project!'),
-        '',
-        ux.colorize('gray', 'Configuration files are located in:'),
-        ux.colorize('cyan', targetDir),
-        '',
-        ux.colorize('yellow', instructions)
-      ].join('\n')
-    );
+    const lines = [
+      ux.colorize('green', 'Created PowerSync self-hosted project!'),
+      '',
+      ux.colorize('cyan', 'Configuration files are located in:'),
+      ux.colorize('gray', targetDir),
+      '',
+      ux.colorize('yellow', instructions)
+    ];
+    if (vscode) {
+      lines.splice(5, 0, ux.colorize('gray', 'Added .vscode/settings.json for YAML !env tag support.'));
+      lines.splice(6, 0, '');
+    }
+    this.log(lines.join('\n'));
   }
 }