feat: improved YAML comments for pull operations

Author: stevensJourney

.changeset/witty-cobras-run.md

@@ -0,0 +1,5 @@
+---
+'powersync': patch
+---
+
+Added YAML comments to the configuration files genered when running powersync pull instance

cli/README.md

@@ -239,7 +239,7 @@ $ npm install -g powersync
 $ powersync COMMAND
 running command...
 $ powersync (--version)
-powersync/0.9.2 linux-x64 node-v24.14.0
+powersync/0.9.2 darwin-arm64 node-v24.13.0
 $ powersync --help [COMMAND]
 USAGE
   $ powersync COMMAND

cli/bin/dev.js

@@ -11,12 +11,18 @@ setCliClientHeaders({
   'user-agent': `POWERSYNC_CLI/${packageJSON.version}`
 });
 
+// Ensure pnpm scripts run in the shell's original cwd (pnpm sets INIT_CWD for this).
+if (process.env.INIT_CWD && process.env.INIT_CWD !== process.cwd()) {
+  process.chdir(process.env.INIT_CWD);
+}
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 await execute({
   development: true,
-  dir: import.meta.url,
+  // Force oclif to ignore the baked manifest so it resolves commands from TS via tsx.
   loadOptions: {
+    ignoreManifest: true,
     root: path.resolve(__dirname, '..')
   }
 });

cli/package.json

@@ -120,6 +120,7 @@
   "scripts": {
     "dev": "tsx bin/dev.js",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "build:ts": "tsc -b",
     "build": "tsc -b && pnpm prepack",
     "lint": "eslint",
     "postpack": "shx rm -f oclif.manifest.json",

cli/src/commands/init/cloud.ts

@@ -9,10 +9,12 @@ import {
   YAML_SERVICE_SCHEMA,
   YAML_SYNC_RULES_SCHEMA
 } from '@powersync/cli-core';
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { buildServiceYaml } from '../../utils/build-service-yaml.js';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
 
@@ -48,13 +50,25 @@ export default class InitCloud extends InstanceCommand {
     }
 
     mkdirSync(targetDir, { recursive: true });
-    cpSync(templatePath, targetDir, { recursive: true });
+    copyFileSync(join(templatePath, CLI_FILENAME), join(targetDir, CLI_FILENAME));
+    copyFileSync(join(templatePath, SYNC_FILENAME), join(targetDir, SYNC_FILENAME));
 
     const servicePath = join(targetDir, SERVICE_FILENAME);
     const syncPath = join(targetDir, SYNC_FILENAME);
     const cliPath = join(targetDir, CLI_FILENAME);
 
-    writeFileSync(servicePath, `${YAML_SERVICE_SCHEMA}\n\n${readFileSync(servicePath, 'utf8')}`);
+    const serviceTemplatePath = join(templatePath, 'service.template.yaml');
+    const renderedServiceYaml = buildServiceYaml({
+      baseConfig: {
+        _type: 'cloud',
+        name: 'my-cli-instance',
+        region: 'us'
+      },
+      schemaHeader: YAML_SERVICE_SCHEMA,
+      templatePath: serviceTemplatePath
+    });
+
+    writeFileSync(servicePath, renderedServiceYaml);
     writeFileSync(syncPath, `${YAML_SYNC_RULES_SCHEMA}\n\n${readFileSync(syncPath, 'utf8')}`);
     writeFileSync(cliPath, `${YAML_CLI_SCHEMA}\n\n${readFileSync(cliPath, 'utf8')}`);
 

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

@@ -9,10 +9,13 @@ import {
   YAML_SERVICE_SCHEMA,
   YAML_SYNC_RULES_SCHEMA
 } from '@powersync/cli-core';
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { BaseServiceSelfHostedConfig } from '@powersync/cli-schemas';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { buildServiceYaml } from '../../utils/build-service-yaml.js';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
 
@@ -48,13 +51,38 @@ export default class InitSelfHosted extends InstanceCommand {
     }
 
     mkdirSync(targetDir, { recursive: true });
-    cpSync(templatePath, targetDir, { recursive: true });
+    copyFileSync(join(templatePath, CLI_FILENAME), join(targetDir, CLI_FILENAME));
+    copyFileSync(join(templatePath, SYNC_FILENAME), join(targetDir, SYNC_FILENAME));
 
     const servicePath = join(targetDir, SERVICE_FILENAME);
     const syncPath = join(targetDir, SYNC_FILENAME);
     const cliPath = join(targetDir, CLI_FILENAME);
 
-    writeFileSync(servicePath, `${YAML_SERVICE_SCHEMA}\n\n${readFileSync(servicePath, 'utf8')}`);
+    const serviceTemplatePath = join(templatePath, 'service.template.yaml');
+    const renderedServiceYaml = buildServiceYaml({
+      baseConfig: {
+        _type: 'self-hosted',
+        api: {
+          tokens: ['use_a_better_token_in_production']
+        },
+        replication: {
+          connections: []
+        },
+        // This is just used as a placeholder
+        storage: {} as BaseServiceSelfHostedConfig['storage'],
+        sync_config: {
+          path: 'sync-config.yaml'
+        },
+        telemetry: {
+          disable_telemetry_sharing: false
+        }
+      },
+      schemaHeader: YAML_SERVICE_SCHEMA,
+      templatePath: serviceTemplatePath,
+      templateReplacementPaths: [['storage']]
+    });
+
+    writeFileSync(servicePath, renderedServiceYaml);
     writeFileSync(syncPath, `${YAML_SYNC_RULES_SCHEMA}\n\n${readFileSync(syncPath, 'utf8')}`);
     writeFileSync(cliPath, `${YAML_CLI_SCHEMA}\n\n${readFileSync(cliPath, 'utf8')}`);
 

cli/src/commands/pull/instance.ts

@@ -11,20 +11,23 @@ import {
 } from '@powersync/cli-core';
 import { ServiceCloudConfig } from '@powersync/cli-schemas';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { stringify } from 'yaml';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { decodeFetchedCloudConfig } from '../../api/cloud/fetch-cloud-config.js';
 import { validateCloudLinkConfig } from '../../api/cloud/validate-cloud-link-config.js';
 import { writeCloudLink } from '../../api/cloud/write-cloud-link.js';
+import { buildServiceYaml } from '../../utils/build-service-yaml.js';
 
 const SERVICE_FETCHED_FILENAME = 'service-fetched.yaml';
 const SYNC_FETCHED_FILENAME = 'sync-fetched.yaml';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
+
 const PULL_CONFIG_HEADER = `# PowerSync Cloud config (fetched from cloud)
 # yaml-language-server: $schema=https://unpkg.com/@powersync/cli-schemas@latest/json-schema/service-config.json
-#
-`;
+`.trim();
 
 export default class PullInstance extends CloudInstanceCommand {
   static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
@@ -124,7 +127,13 @@ export default class PullInstance extends CloudInstanceCommand {
       );
     }
 
-    const serviceYaml = PULL_CONFIG_HEADER + stringify(ServiceCloudConfig.encode(fetched.config));
+    const fetchedEncodedConfig = ServiceCloudConfig.encode(fetched.config);
+    const serviceTemplatePath = join(TEMPLATES_DIR, 'cloud', 'powersync', 'service.template.yaml');
+    const serviceYaml = buildServiceYaml({
+      baseConfig: fetchedEncodedConfig,
+      schemaHeader: PULL_CONFIG_HEADER,
+      templatePath: serviceTemplatePath
+    });
 
     const serviceOutputName = serviceExists ? SERVICE_FETCHED_FILENAME : SERVICE_FILENAME;
     const serviceOutputPath = join(projectDir, serviceOutputName);