postgresai 0.15.0-dev.5 → 0.15.0-dev.7

package/bin/postgres-ai.ts

@@ -7,6 +7,7 @@ import * as yaml from "js-yaml";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { fileURLToPath } from "url";
 import * as crypto from "node:crypto";
 import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
@@ -477,14 +478,14 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
     fs.mkdirSync(projectDir, { recursive: true, mode: 0o700 });
   }
 
-  const refs = [
-    process.env.PGAI_PROJECT_REF,
-    pkg.version,
-    `v${pkg.version}`,
-    "main",
-  ].filter((v): v is string => Boolean(v && v.trim()));
-
   if (!fs.existsSync(composeFile)) {
+    const refs = [
+      process.env.PGAI_PROJECT_REF,
+      pkg.version,
+      `v${pkg.version}`,
+      "main",
+    ].filter((v): v is string => Boolean(v && v.trim()));
+
     let lastErr: unknown;
     for (const ref of refs) {
       const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
@@ -503,22 +504,11 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
     }
   }
 
-  // Download instances.demo.yml (demo target template) if not present
-  const demoFile = path.resolve(projectDir, "instances.demo.yml");
-  if (!fs.existsSync(demoFile)) {
-    for (const ref of refs) {
-      const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/instances.demo.yml`;
-      try {
-        const text = await downloadText(url);
-        fs.writeFileSync(demoFile, text, { encoding: "utf8", mode: 0o600 });
-        break;
-      } catch {
-        // non-fatal — demo file is optional
-      }
-    }
+  // Ensure instances.yml exists as a FILE (avoid Docker creating a directory).
+  // Docker bind-mounts create missing paths as directories; replace if so.
+  if (fs.existsSync(instancesFile) && fs.lstatSync(instancesFile).isDirectory()) {
+    fs.rmSync(instancesFile, { recursive: true, force: true });
   }
-
-  // Ensure instances.yml exists as a FILE (avoid Docker creating a directory)
   if (!fs.existsSync(instancesFile)) {
     const header =
       "# PostgreSQL instances to monitor\n" +
@@ -2317,7 +2307,7 @@ mon
     console.log("This will install, configure, and start the monitoring system\n");
 
     // Ensure we have a project directory with docker-compose.yml even if running from elsewhere
-    const { projectDir } = await resolveOrInitPaths();
+    const { projectDir, instancesFile: instancesPath } = await resolveOrInitPaths();
     console.log(`Project directory: ${projectDir}\n`);
 
     // Save project name to .pgwatch-config if provided (used by reporter container)
@@ -2540,15 +2530,37 @@ mon
         }
       }
     } else {
-      // Demo mode: copy instances.demo.yml → instances.yml so the demo target is active
+      // Demo mode: configure instances.yml from the bundled demo template.
+      //
+      // Side effects:
+      //   - Writes instancesPath (instances.yml next to docker-compose.yml)
+      //   - If Docker previously bind-mounted instances.yml as a directory, removes it first.
+      //
+      // Failure modes:
+      //   - Exits with code 1 if instances.demo.yml is not found in any candidate path.
+      //     This is fatal because starting without a target produces empty dashboards that
+      //     look like a bug rather than a misconfiguration.
+      //
+      // Template search order (import.meta.url is resolved at runtime, not baked in at build):
+      //   1. npm layout:  dist/bin/../../instances.demo.yml  →  package-root/instances.demo.yml
+      //   2. dev layout:  cli/bin/../../../instances.demo.yml →  repo-root/instances.demo.yml
       console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database");
-      const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
-      const demoSrc = path.resolve(projectDir, "instances.demo.yml");
-      if (fs.existsSync(demoSrc)) {
+      const currentDir = path.dirname(fileURLToPath(import.meta.url));
+      const demoCandidates = [
+        path.resolve(currentDir, "..", "..", "instances.demo.yml"),        // npm: dist/bin -> package root
+        path.resolve(currentDir, "..", "..", "..", "instances.demo.yml"),  // dev: cli/bin -> repo root
+      ];
+      const demoSrc = demoCandidates.find(p => fs.existsSync(p));
+      if (demoSrc) {
+        // Remove directory artifact left by Docker bind-mounts before copying
+        if (fs.existsSync(instancesPath) && fs.lstatSync(instancesPath).isDirectory()) {
+          fs.rmSync(instancesPath, { recursive: true, force: true });
+        }
         fs.copyFileSync(demoSrc, instancesPath);
         console.log("✓ Demo monitoring target configured\n");
       } else {
-        console.error("⚠ instances.demo.yml not found — demo target not configured\n");
+        console.error(`Error: instances.demo.yml not found — cannot configure demo target.\nSearched: ${demoCandidates.join(", ")}\n`);
+        process.exit(1);
       }
     }
 
@@ -2904,7 +2916,7 @@ mon
     console.log(`Project Directory: ${projectDir}`);
     console.log(`Docker Compose File: ${composeFile}`);
     console.log(`Instances File: ${instancesFile}`);
-    if (fs.existsSync(instancesFile)) {
+    if (fs.existsSync(instancesFile) && !fs.lstatSync(instancesFile).isDirectory()) {
       console.log("\nInstances configuration:\n");
       const text = fs.readFileSync(instancesFile, "utf8");
       process.stdout.write(text);
@@ -3120,7 +3132,7 @@ targets
   .description("list monitoring target databases")
   .action(async () => {
     const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
-    if (!fs.existsSync(instancesPath)) {
+    if (!fs.existsSync(instancesPath) || fs.lstatSync(instancesPath).isDirectory()) {
       console.error(`instances.yml not found in ${projectDir}`);
       process.exitCode = 1;
       return;
@@ -3186,7 +3198,7 @@ targets
 
     // Check if instance already exists
     try {
-      if (fs.existsSync(file)) {
+      if (fs.existsSync(file) && !fs.lstatSync(file).isDirectory()) {
         const content = fs.readFileSync(file, "utf8");
         const instances = yaml.load(content) as Instance[] | null || [];
         if (Array.isArray(instances)) {
@@ -3200,7 +3212,8 @@ targets
       }
     } catch (err) {
       // If YAML parsing fails, fall back to simple check
-      const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+      const isFile = fs.existsSync(file) && !fs.lstatSync(file).isDirectory();
+      const content = isFile ? fs.readFileSync(file, "utf8") : "";
       if (new RegExp(`^- name: ${instanceName}$`, "m").test(content)) {
         console.error(`Monitoring target '${instanceName}' already exists`);
         process.exitCode = 1;
@@ -3208,7 +3221,10 @@ targets
       }
     }
 
-    // Add new instance
+    // Add new instance — if instances.yml is a directory (Docker artifact), replace it with a file
+    if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+      fs.rmSync(file, { recursive: true, force: true });
+    }
     const body = `- name: ${instanceName}\n  conn_str: ${connStr}\n  preset_metrics: full\n  custom_metrics:\n  is_enabled: true\n  group: default\n  custom_tags:\n    env: production\n    cluster: default\n    node_name: ${instanceName}\n    sink_type: ~sink_type~\n`;
     const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
     fs.appendFileSync(file, (content && !/\n$/.test(content) ? "\n" : "") + body, "utf8");
@@ -3219,7 +3235,7 @@ targets
   .description("remove monitoring target database")
   .action(async (name: string) => {
     const { instancesFile: file } = await resolveOrInitPaths();
-    if (!fs.existsSync(file)) {
+    if (!fs.existsSync(file) || fs.lstatSync(file).isDirectory()) {
       console.error("instances.yml not found");
       process.exitCode = 1;
       return;
@@ -3256,7 +3272,7 @@ targets
   .description("test monitoring target database connectivity")
   .action(async (name: string) => {
     const { instancesFile: instancesPath } = await resolveOrInitPaths();
-    if (!fs.existsSync(instancesPath)) {
+    if (!fs.existsSync(instancesPath) || fs.lstatSync(instancesPath).isDirectory()) {
       console.error("instances.yml not found");
       process.exitCode = 1;
       return;

package/dist/bin/postgres-ai.js

@@ -13151,7 +13151,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.15.0-dev.5",
+  version: "0.15.0-dev.7",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -15965,6 +15965,7 @@ var safeDump = renamed("safeDump", "dump");
 import * as fs6 from "fs";
 import * as path6 from "path";
 import * as os3 from "os";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import * as crypto2 from "crypto";
 
 // node_modules/pg/esm/index.mjs
@@ -15981,7 +15982,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.15.0-dev.5";
+var version = "0.15.0-dev.7";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -29867,13 +29868,13 @@ async function ensureDefaultMonitoringProject() {
   if (!fs6.existsSync(projectDir)) {
     fs6.mkdirSync(projectDir, { recursive: true, mode: 448 });
   }
-  const refs = [
-    process.env.PGAI_PROJECT_REF,
-    package_default.version,
-    `v${package_default.version}`,
-    "main"
-  ].filter((v) => Boolean(v && v.trim()));
   if (!fs6.existsSync(composeFile)) {
+    const refs = [
+      process.env.PGAI_PROJECT_REF,
+      package_default.version,
+      `v${package_default.version}`,
+      "main"
+    ].filter((v) => Boolean(v && v.trim()));
     let lastErr;
     for (const ref of refs) {
       const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
@@ -29890,16 +29891,8 @@ async function ensureDefaultMonitoringProject() {
       throw new Error(`Failed to bootstrap docker-compose.yml: ${msg}`);
     }
   }
-  const demoFile = path6.resolve(projectDir, "instances.demo.yml");
-  if (!fs6.existsSync(demoFile)) {
-    for (const ref of refs) {
-      const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/instances.demo.yml`;
-      try {
-        const text = await downloadText(url);
-        fs6.writeFileSync(demoFile, text, { encoding: "utf8", mode: 384 });
-        break;
-      } catch {}
-    }
+  if (fs6.existsSync(instancesFile) && fs6.lstatSync(instancesFile).isDirectory()) {
+    fs6.rmSync(instancesFile, { recursive: true, force: true });
   }
   if (!fs6.existsSync(instancesFile)) {
     const header = `# PostgreSQL instances to monitor
@@ -31317,7 +31310,7 @@ mon.command("local-install").description("install local monitoring stack (genera
 `);
   console.log(`This will install, configure, and start the monitoring system
 `);
-  const { projectDir } = await resolveOrInitPaths();
+  const { projectDir, instancesFile: instancesPath } = await resolveOrInitPaths();
   console.log(`Project directory: ${projectDir}
 `);
   if (opts.project) {
@@ -31428,13 +31421,13 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
   if (!opts.demo) {
     console.log(`Step 2: Add PostgreSQL Instance to Monitor
 `);
-    const { instancesFile: instancesPath, projectDir: projectDir2 } = await resolveOrInitPaths();
+    const { instancesFile: instancesPath2, projectDir: projectDir2 } = await resolveOrInitPaths();
     const emptyInstancesContent = `# PostgreSQL instances to monitor
 # Add your instances using: postgres-ai mon targets add
 
 `;
-    fs6.writeFileSync(instancesPath, emptyInstancesContent, "utf8");
-    console.log(`Instances file: ${instancesPath}`);
+    fs6.writeFileSync(instancesPath2, emptyInstancesContent, "utf8");
+    console.log(`Instances file: ${instancesPath2}`);
     console.log(`Project directory: ${projectDir2}
 `);
     if (opts.dbUrl) {
@@ -31465,7 +31458,7 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
     node_name: ${instanceName}
     sink_type: ~sink_type~
 `;
-      fs6.appendFileSync(instancesPath, body, "utf8");
+      fs6.appendFileSync(instancesPath2, body, "utf8");
       console.log(`\u2713 Monitoring target '${instanceName}' added
 `);
       console.log("Testing connection to the added instance...");
@@ -31520,7 +31513,7 @@ You can provide either:`);
     node_name: ${instanceName}
     sink_type: ~sink_type~
 `;
-            fs6.appendFileSync(instancesPath, body, "utf8");
+            fs6.appendFileSync(instancesPath2, body, "utf8");
             console.log(`\u2713 Monitoring target '${instanceName}' added
 `);
             console.log("Testing connection to the added instance...");
@@ -31549,15 +31542,24 @@ You can provide either:`);
     }
   } else {
     console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database");
-    const { instancesFile: instancesPath, projectDir: projectDir2 } = await resolveOrInitPaths();
-    const demoSrc = path6.resolve(projectDir2, "instances.demo.yml");
-    if (fs6.existsSync(demoSrc)) {
+    const currentDir = path6.dirname(fileURLToPath2(import.meta.url));
+    const demoCandidates = [
+      path6.resolve(currentDir, "..", "..", "instances.demo.yml"),
+      path6.resolve(currentDir, "..", "..", "..", "instances.demo.yml")
+    ];
+    const demoSrc = demoCandidates.find((p) => fs6.existsSync(p));
+    if (demoSrc) {
+      if (fs6.existsSync(instancesPath) && fs6.lstatSync(instancesPath).isDirectory()) {
+        fs6.rmSync(instancesPath, { recursive: true, force: true });
+      }
       fs6.copyFileSync(demoSrc, instancesPath);
       console.log(`\u2713 Demo monitoring target configured
 `);
     } else {
-      console.error(`\u26A0 instances.demo.yml not found \u2014 demo target not configured
+      console.error(`Error: instances.demo.yml not found \u2014 cannot configure demo target.
+Searched: ${demoCandidates.join(", ")}
 `);
+      process.exit(1);
     }
   }
   console.log(opts.demo ? "Step 3: Updating configuration..." : "Step 3: Updating configuration...");
@@ -31845,7 +31847,7 @@ mon.command("config").description("show monitoring services configuration").acti
   console.log(`Project Directory: ${projectDir}`);
   console.log(`Docker Compose File: ${composeFile}`);
   console.log(`Instances File: ${instancesFile}`);
-  if (fs6.existsSync(instancesFile)) {
+  if (fs6.existsSync(instancesFile) && !fs6.lstatSync(instancesFile).isDirectory()) {
     console.log(`
 Instances configuration:
 `);
@@ -32020,7 +32022,7 @@ mon.command("check").description("monitoring services system readiness check").a
 var targets = mon.command("targets").description("manage databases to monitor");
 targets.command("list").description("list monitoring target databases").action(async () => {
   const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
-  if (!fs6.existsSync(instancesPath)) {
+  if (!fs6.existsSync(instancesPath) || fs6.lstatSync(instancesPath).isDirectory()) {
     console.error(`instances.yml not found in ${projectDir}`);
     process.exitCode = 1;
     return;
@@ -32075,7 +32077,7 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
   const db = m[5];
   const instanceName = name && name.trim() ? name.trim() : `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
   try {
-    if (fs6.existsSync(file)) {
+    if (fs6.existsSync(file) && !fs6.lstatSync(file).isDirectory()) {
       const content2 = fs6.readFileSync(file, "utf8");
       const instances = load(content2) || [];
       if (Array.isArray(instances)) {
@@ -32088,13 +32090,17 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
       }
     }
   } catch (err) {
-    const content2 = fs6.existsSync(file) ? fs6.readFileSync(file, "utf8") : "";
+    const isFile = fs6.existsSync(file) && !fs6.lstatSync(file).isDirectory();
+    const content2 = isFile ? fs6.readFileSync(file, "utf8") : "";
     if (new RegExp(`^- name: ${instanceName}$`, "m").test(content2)) {
       console.error(`Monitoring target '${instanceName}' already exists`);
       process.exitCode = 1;
       return;
     }
   }
+  if (fs6.existsSync(file) && fs6.lstatSync(file).isDirectory()) {
+    fs6.rmSync(file, { recursive: true, force: true });
+  }
   const body = `- name: ${instanceName}
   conn_str: ${connStr}
   preset_metrics: full
@@ -32114,7 +32120,7 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
 });
 targets.command("remove <name>").description("remove monitoring target database").action(async (name) => {
   const { instancesFile: file } = await resolveOrInitPaths();
-  if (!fs6.existsSync(file)) {
+  if (!fs6.existsSync(file) || fs6.lstatSync(file).isDirectory()) {
     console.error("instances.yml not found");
     process.exitCode = 1;
     return;
@@ -32143,7 +32149,7 @@ targets.command("remove <name>").description("remove monitoring target database"
 });
 targets.command("test <name>").description("test monitoring target database connectivity").action(async (name) => {
   const { instancesFile: instancesPath } = await resolveOrInitPaths();
-  if (!fs6.existsSync(instancesPath)) {
+  if (!fs6.existsSync(instancesPath) || fs6.lstatSync(instancesPath).isDirectory()) {
     console.error("instances.yml not found");
     process.exitCode = 1;
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.15.0-dev.5",
+  "version": "0.15.0-dev.7",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/init.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeAll, afterAll } from "bun:test";
-import { resolve } from "path";
+import path, { resolve } from "path";
 import * as fs from "fs";
 import * as os from "os";
 
@@ -1070,6 +1070,69 @@ describe("CLI commands", () => {
     expect(r.stderr).toMatch(/Reports will be generated locally only/);
   });
 
+  test("cli: mon local-install --demo configures demo monitoring target", () => {
+    // --demo should copy instances.demo.yml to instances.yml and print confirmation.
+    // The command will fail later (no Docker), but we verify the demo target step succeeded.
+    // resolvePaths() walks cwd() up to find docker-compose.yml, so instances.yml
+    // is written next to docker-compose.yml in the repo root.
+    const repoRoot = resolve(import.meta.dir, "..", "..");
+    const instancesPath = path.join(repoRoot, "instances.yml");
+    // Remove instances.yml if it exists — use rmSync to handle both files and
+    // directories (the EISDIR test may have left a directory here if it failed).
+    if (fs.existsSync(instancesPath)) fs.rmSync(instancesPath, { recursive: true, force: true });
+    try {
+      const r = runCli(["mon", "local-install", "--demo"]);
+      expect(r.stdout).toMatch(/Demo mode enabled/);
+      expect(r.stdout).toMatch(/Demo monitoring target configured/);
+      // Verify instances.yml was actually written with the demo target
+      expect(fs.existsSync(instancesPath)).toBe(true);
+      const content = fs.readFileSync(instancesPath, "utf8");
+      expect(content).toContain("name: target_database");
+      expect(content).toContain("conn_str: postgresql://monitor:monitor_pass@target-db:5432/target_database");
+    } finally {
+      // Clean up — instances.yml is gitignored so safe to remove
+      if (fs.existsSync(instancesPath)) fs.rmSync(instancesPath, { recursive: true, force: true });
+    }
+  });
+
+  test("cli: mon local-install --demo exits with code 1 when instances.demo.yml is missing", () => {
+    // Regression: if instances.demo.yml cannot be found in any candidate path, the CLI
+    // must exit with a non-zero code and a descriptive error (not silently create empty dashboards).
+    const repoRoot = resolve(import.meta.dir, "..", "..");
+    const demoFile = path.join(repoRoot, "instances.demo.yml");
+    const tempBackup = path.join(os.tmpdir(), `instances.demo.yml.test-backup-${Date.now()}`);
+    // Temporarily move instances.demo.yml so neither candidate path resolves
+    fs.copyFileSync(demoFile, tempBackup);
+    fs.unlinkSync(demoFile);
+    try {
+      const r = runCli(["mon", "local-install", "--demo"]);
+      expect(r.status).not.toBe(0);
+      expect(r.stderr).toContain("instances.demo.yml not found");
+    } finally {
+      // Restore the file — critical to do before any assertion can throw
+      if (!fs.existsSync(demoFile)) fs.copyFileSync(tempBackup, demoFile);
+      fs.rmSync(tempBackup, { force: true });
+    }
+  });
+
+  test("cli: mon local-install --demo with EISDIR recovers instances.yml", () => {
+    // Docker bind-mounts create missing paths as directories; the CLI must handle this.
+    const repoRoot = resolve(import.meta.dir, "..", "..");
+    const instancesPath = path.join(repoRoot, "instances.yml");
+    // Create instances.yml as a directory (simulating Docker artifact)
+    if (fs.existsSync(instancesPath)) fs.rmSync(instancesPath, { recursive: true, force: true });
+    fs.mkdirSync(instancesPath);
+    try {
+      const r = runCli(["mon", "local-install", "--demo"]);
+      expect(r.stdout).toMatch(/Demo monitoring target configured/);
+      expect(fs.statSync(instancesPath).isFile()).toBe(true);
+      const content = fs.readFileSync(instancesPath, "utf8");
+      expect(content).toContain("name: target_database");
+    } finally {
+      if (fs.existsSync(instancesPath)) fs.rmSync(instancesPath, { recursive: true, force: true });
+    }
+  });
+
   test("cli: mon local-install --demo with global --api-key shows error", () => {
     // When --demo is used with global --api-key, it should still be detected and error
     const r = runCli([

package/test/monitoring.test.ts

@@ -259,3 +259,81 @@ describe("registerMonitoringInstance", () => {
     expect(fetchCalls[0].url).toBe("https://custom.api.com/v2/rpc/monitoring_instance_register");
   });
 });
+
+describe("demo mode instances.demo.yml", () => {
+  const repoRoot = path.resolve(import.meta.dir, "..", "..");
+
+  test("instances.demo.yml exists in repo root", () => {
+    const demoFile = path.join(repoRoot, "instances.demo.yml");
+    expect(fs.existsSync(demoFile)).toBe(true);
+  });
+
+  test("instances.demo.yml contains demo target connection", () => {
+    const demoFile = path.join(repoRoot, "instances.demo.yml");
+    const content = fs.readFileSync(demoFile, "utf8");
+    expect(content).toContain("name: target_database");
+    expect(content).toContain("conn_str: postgresql://monitor:monitor_pass@target-db:5432/target_database");
+    expect(content).toContain("is_enabled: true");
+    expect(content).toContain("preset_metrics: full");
+  });
+
+  test("instances.demo.yml has required YAML structure", () => {
+    const demoFile = path.join(repoRoot, "instances.demo.yml");
+    const content = fs.readFileSync(demoFile, "utf8");
+    // Verify it's a YAML list (starts with "- name:")
+    expect(content).toMatch(/^- name: target_database/m);
+    // Verify required fields are present with correct indentation
+    expect(content).toMatch(/^\s+conn_str:/m);
+    expect(content).toMatch(/^\s+preset_metrics: full/m);
+    expect(content).toMatch(/^\s+is_enabled: true/m);
+    // ~sink_type~ is a sed token substituted by generate-pgwatch-sources.sh; values: postgres, prometheus
+    expect(content).toMatch(/^\s+sink_type: ~sink_type~/m);
+  });
+
+  test("instances.yml is gitignored (not tracked)", () => {
+    const gitignore = fs.readFileSync(path.join(repoRoot, ".gitignore"), "utf8");
+    expect(gitignore).toMatch(/^instances\.yml$/m);
+  });
+
+  test("demo config can be copied to instances.yml in temp dir", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "demo-install-test-"));
+    try {
+      const demoSrc = path.join(repoRoot, "instances.demo.yml");
+      const instancesDest = path.join(tempDir, "instances.yml");
+
+      fs.copyFileSync(demoSrc, instancesDest);
+
+      expect(fs.existsSync(instancesDest)).toBe(true);
+      const content = fs.readFileSync(instancesDest, "utf8");
+      expect(content).toContain("name: target_database");
+      expect(content).toContain("conn_str: postgresql://monitor:monitor_pass@target-db:5432/target_database");
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test("demo config copy overwrites directory at instances.yml path", () => {
+    // Docker bind-mounts create missing paths as directories; the copy must handle this
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "demo-eisdir-test-"));
+    try {
+      const demoSrc = path.join(repoRoot, "instances.demo.yml");
+      const instancesDest = path.join(tempDir, "instances.yml");
+
+      // Simulate Docker creating a directory at instances.yml path
+      fs.mkdirSync(instancesDest);
+      expect(fs.statSync(instancesDest).isDirectory()).toBe(true);
+
+      // The fix: remove directory then copy
+      if (fs.statSync(instancesDest).isDirectory()) {
+        fs.rmSync(instancesDest, { recursive: true, force: true });
+      }
+      fs.copyFileSync(demoSrc, instancesDest);
+
+      expect(fs.statSync(instancesDest).isFile()).toBe(true);
+      const content = fs.readFileSync(instancesDest, "utf8");
+      expect(content).toContain("name: target_database");
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+});