@ngocsangairvds/vsaf 4.1.7 → 4.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "4.1.7",
+  "version": "4.1.8",
   "description": "logging step",
   "main": "packages/core/dist/index.js",
   "types": "packages/core/dist/index.d.ts",

package/skills/vds-skill/install-deps.mjs

@@ -10,12 +10,13 @@
  *   node install-deps.mjs [projectPath]
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, chmodSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, chmodSync, unlinkSync, renameSync } from 'fs';
 import { join, dirname, delimiter } from 'path';
 import { homedir } from 'os';
 
 const projectPath = process.argv[2] || process.cwd();
 const packDir = process.argv[3] || dirname(new URL(import.meta.url).pathname);
+const skipMigration = process.argv.includes('--skip-migration');
 
 // ── Config ──
 
@@ -57,13 +58,169 @@ function parseExistingConfig(filePath) {
   return vars;
 }
 
-// ── Step 1: Ensure ~/.vds/ directory ──
+// ── Migration: sdlc-config.env → .env ──
+
+const LEGACY_CONFIG = join(VDS_DIR, 'sdlc-config.env');
+
+const VAR_MAPPING = {
+  'VDS_CONFLUENCE_TOKEN': 'INTERNAL_CONFLUENCE_TOKEN',
+  'VDS_JIRA_TOKEN': 'JIRA_TOKEN',
+  'VDS_BITBUCKET_TOKEN': 'BITBUCKET_TOKEN',
+  'VDS_USERNAME': 'VDS_USERNAME',
+  'VDS_PASSWORD': 'VDS_PASSWORD',
+  'VDS_CONFLUENCE_SPACE_DEFAULT': 'VDS_CONFLUENCE_SPACE_DEFAULT',
+  'VDS_JIRA_PROJECT_DEFAULT': 'VDS_JIRA_PROJECT_DEFAULT',
+};
+
+const PLACEHOLDERS = new Set([
+  'changeme', '<your-token>', 'xxx', 'todo',
+  'your-confluence-token', 'your-jira-token', 'your-bitbucket-token',
+]);
+
+function parseLegacyEnv(filePath) {
+  if (!existsSync(filePath)) return {};
+  let raw = readFileSync(filePath);
+  // Strip UTF-8 BOM
+  if (raw[0] === 0xEF && raw[1] === 0xBB && raw[2] === 0xBF) {
+    raw = raw.subarray(3);
+  }
+  const text = raw.toString('utf-8');
+  const vars = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice(7).trimStart();
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    if (val.length >= 2 && val[0] === val[val.length - 1] && (val[0] === "'" || val[0] === '"')) {
+      val = val.slice(1, -1);
+    }
+    if (val) vars[key] = val;
+  }
+  return vars;
+}
+
+function migrateSdlcConfig() {
+  if (!existsSync(LEGACY_CONFIG)) {
+    log('ℹ️', 'No legacy sdlc-config.env found — skip migration.');
+    return;
+  }
+
+  const legacy = parseLegacyEnv(LEGACY_CONFIG);
+  if (Object.keys(legacy).length === 0) {
+    log('ℹ️', 'sdlc-config.env is empty — skip migration.');
+    return;
+  }
+
+  const target = parseExistingConfig(CONFIG_FILE);
+
+  const toWrite = {};
+  const migrated = [];
+  const skipped = [];
+  const warnings = [];
+
+  for (const [oldKey, value] of Object.entries(legacy)) {
+    if (!(oldKey in VAR_MAPPING)) {
+      warnings.push(oldKey);
+      continue;
+    }
+    const newKey = VAR_MAPPING[oldKey];
+    if (PLACEHOLDERS.has(value.toLowerCase())) {
+      skipped.push(oldKey);
+      continue;
+    }
+    // Don't overwrite real values
+    const existing = target[newKey] || '';
+    if (existing && !PLACEHOLDERS.has(existing.toLowerCase())) {
+      continue;
+    }
+    toWrite[newKey] = value;
+    migrated.push(newKey);
+  }
+
+  if (migrated.length === 0) {
+    log('ℹ️', 'Nothing to migrate — target already has all values.');
+    if (warnings.length > 0) {
+      log('⚠️', `Unknown keys in sdlc-config.env: ${warnings.join(', ')}`);
+    }
+    return;
+  }
+
+  // Backup existing .env
+  if (existsSync(CONFIG_FILE)) {
+    const ts = Math.floor(Date.now() / 1000);
+    const backup = join(VDS_DIR, `.env.bak.${ts}`);
+    writeFileSync(backup, readFileSync(CONFIG_FILE));
+    log('📋', `Backup: ${backup}`);
+  }
+
+  // Read existing content or start fresh
+  let lines = existsSync(CONFIG_FILE)
+    ? readFileSync(CONFIG_FILE, 'utf-8').split('\n')
+    : [];
+
+  // Update in-place where key exists with empty value
+  const updated = new Set();
+  lines = lines.map(line => {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith('#')) return line;
+    const eq = stripped.indexOf('=');
+    if (eq <= 0) return line;
+    const key = stripped.slice(0, eq).trim();
+    if (key in toWrite) {
+      updated.add(key);
+      return `${key}=${toWrite[key]}`;
+    }
+    return line;
+  });
+
+  // Append remaining
+  const remaining = Object.entries(toWrite).filter(([k]) => !updated.has(k));
+  if (remaining.length > 0) {
+    if (lines.length > 0 && lines[lines.length - 1].trim() !== '') lines.push('');
+    lines.push('# --- Migrated from sdlc-config.env ---');
+    for (const [key, val] of remaining) {
+      lines.push(`${key}=${val}`);
+    }
+  }
+
+  // Atomic write
+  const tmp = join(VDS_DIR, '.env.tmp');
+  writeFileSync(tmp, lines.join('\n') + '\n');
+  if (process.platform !== 'win32') {
+    chmodSync(tmp, 0o600);
+  }
+  renameSync(tmp, CONFIG_FILE);
+
+  log('✅', `Migrated ${migrated.length} credential(s) from sdlc-config.env:`);
+  for (const name of migrated) {
+    log('  ', `+ ${name}`);
+  }
+  if (skipped.length > 0) {
+    log('ℹ️', `Skipped ${skipped.length} placeholder(s).`);
+  }
+  if (warnings.length > 0) {
+    log('⚠️', `Unknown keys (not migrated): ${warnings.join(', ')}`);
+  }
+  console.log('');
+  log('💡', `Consider removing ${LEGACY_CONFIG} to avoid confusion.`);
+}
+
+// ── Step 0: Migrate legacy sdlc-config.env (if exists) ──
 
 console.log('\n[vds-skill] Setting up VDS credentials...\n');
 
 mkdirSync(VDS_DIR, { recursive: true });
 
-// ── Step 2: Create or merge config template ──
+if (!skipMigration) {
+  migrateSdlcConfig();
+} else {
+  log('ℹ️', 'Migration skipped (--skip-migration).');
+}
+
+// ── Step 1: Create or merge credential template ──
 
 const existing = parseExistingConfig(CONFIG_FILE);
 const missing = [];

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/cli.py

@@ -116,6 +116,38 @@ def env_status() -> None:
             console.print("  4. Set INTERNAL_CONFLUENCE_TOKEN/EXTERNAL_CONFLUENCE_TOKEN (or VDS credentials).")
 
 
+@env_app.command("migrate-sdlc-config")
+def env_migrate_sdlc_config() -> None:
+    """Migrate credentials from legacy ~/.vds/sdlc-config.env to ~/.vds/.env."""
+    from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+    legacy_path = get_shared_env_path().parent / "sdlc-config.env"
+    target_path = get_shared_env_path()
+
+    result = migrate_sdlc_config(legacy_path, target_path)
+
+    if result.legacy_not_found:
+        console.print("[dim]No legacy sdlc-config.env found — nothing to migrate.[/dim]")
+        return
+
+    if result.migrated:
+        console.print("[green]Migrated credentials:[/green]")
+        for name in result.migrated:
+            console.print(f"  [green]+[/green] {name}")
+
+    if result.skipped:
+        console.print(f"\n[dim]Skipped {len(result.skipped)} placeholder(s).[/dim]")
+
+    for warning in result.warnings:
+        console.print(f"[yellow]Warning: {warning}[/yellow]")
+
+    if result.migrated:
+        console.print(f"\n[yellow]Suggestion: rename or remove {legacy_path}[/yellow]")
+        console.print("[yellow]  to avoid confusion on next install.[/yellow]")
+    else:
+        console.print("[dim]Nothing to migrate — target already has all values.[/dim]")
+
+
 @env_app.command("install-git-helper")
 def env_install_git_helper(
     force: bool = typer.Option(

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_cli.py

@@ -203,6 +203,29 @@ def test_cli_status_command(mock_load: Mock, mock_script_dir: Path) -> None:
         assert "Orchestrator" in result.stdout or "Environment" in result.stdout
 
 
+def test_cli_env_migrate_sdlc_config_no_legacy(mock_home_dir: Path) -> None:
+    """When no sdlc-config.env exists, command exits 0 with skip message."""
+    result = runner.invoke(app, ["env", "migrate-sdlc-config"])
+    assert result.exit_code == 0
+    assert "No legacy" in result.stdout or "not found" in result.stdout
+
+
+def test_cli_env_migrate_sdlc_config_with_legacy(mock_home_dir: Path) -> None:
+    """When sdlc-config.env exists, command migrates and reports."""
+    legacy = mock_home_dir / ".vds" / "sdlc-config.env"
+    legacy.parent.mkdir(parents=True, exist_ok=True)
+    legacy.write_text("VDS_CONFLUENCE_TOKEN=test-token\n")
+
+    result = runner.invoke(app, ["env", "migrate-sdlc-config"])
+    assert result.exit_code == 0
+    assert "INTERNAL_CONFLUENCE_TOKEN" in result.stdout
+
+    # Verify target file was created
+    target = mock_home_dir / ".vds" / ".env"
+    assert target.exists()
+    assert "INTERNAL_CONFLUENCE_TOKEN=test-token" in target.read_text()
+
+
 @patch("vds_cli.cli._env_git_helper")
 @patch("vds_cli.cli.validate_orchestrator")
 @patch("vds_cli.cli.load_environment")

package/skills/vds-skill/vds-scripts/vds_cli_common/src/vds_cli_common/migrate_sdlc_config.py

@@ -0,0 +1,210 @@
+"""Migrate credentials from legacy ~/.vds/sdlc-config.env to ~/.vds/.env.
+
+The old installer wrote credentials with wrong variable names to a file
+that vds-cli never reads. This module:
+1. Parses sdlc-config.env
+2. Maps old var names → names the orchestrators actually expect
+3. Merges into ~/.vds/.env without overwriting user-set values
+4. Creates a timestamped backup of .env before modifying
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+# ── Mapping table ──
+# Source: orchestrator config.py files (pydantic alias= fields)
+
+MAPPING: dict[str, str] = {
+    "VDS_CONFLUENCE_TOKEN": "INTERNAL_CONFLUENCE_TOKEN",
+    "VDS_JIRA_TOKEN": "JIRA_TOKEN",
+    "VDS_BITBUCKET_TOKEN": "BITBUCKET_TOKEN",
+    # These pass through unchanged
+    "VDS_USERNAME": "VDS_USERNAME",
+    "VDS_PASSWORD": "VDS_PASSWORD",
+    "VDS_CONFLUENCE_SPACE_DEFAULT": "VDS_CONFLUENCE_SPACE_DEFAULT",
+    "VDS_JIRA_PROJECT_DEFAULT": "VDS_JIRA_PROJECT_DEFAULT",
+}
+
+PLACEHOLDERS = frozenset({
+    "changeme",
+    "<your-token>",
+    "xxx",
+    "todo",
+    "your-confluence-token",
+    "your-jira-token",
+    "your-bitbucket-token",
+})
+
+
+@dataclass
+class MigrationResult:
+    migrated: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    legacy_not_found: bool = False
+
+
+def parse_legacy_env(path: Path) -> dict[str, str]:
+    """Parse a shell-style .env file into {key: value}.
+
+    Handles: comments, blank lines, export prefix, single/double quotes,
+    CRLF line endings, UTF-8 BOM, equals signs in values.
+    Skips entries with empty/whitespace-only values.
+    """
+    if not path.exists():
+        return {}
+
+    raw = path.read_bytes()
+    # Strip UTF-8 BOM
+    if raw.startswith(b"\xef\xbb\xbf"):
+        raw = raw[3:]
+    text = raw.decode("utf-8")
+
+    result: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        eq = line.find("=")
+        if eq <= 0:
+            continue
+        key = line[:eq].strip()
+        val = line[eq + 1:].strip()
+        # Strip matching quotes
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"'):
+            val = val[1:-1]
+        if not val:
+            continue
+        result[key] = val
+    return result
+
+
+def _is_placeholder(value: str) -> bool:
+    return value.lower() in PLACEHOLDERS
+
+
+def _parse_target_active_keys(path: Path) -> dict[str, str]:
+    """Parse target .env, returning only active (uncommented, non-empty) keys."""
+    if not path.exists():
+        return {}
+    result: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("export "):
+            stripped = stripped[7:].lstrip()
+        eq = stripped.find("=")
+        if eq <= 0:
+            continue
+        key = stripped[:eq].strip()
+        val = stripped[eq + 1:].strip()
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"'):
+            val = val[1:-1]
+        result[key] = val
+    return result
+
+
+def migrate_sdlc_config(
+    legacy_path: Path,
+    target_path: Path,
+) -> MigrationResult:
+    """Migrate credentials from sdlc-config.env → .env.
+
+    Args:
+        legacy_path: Path to ~/.vds/sdlc-config.env
+        target_path: Path to ~/.vds/.env
+
+    Returns:
+        MigrationResult with lists of migrated, skipped, and warning entries.
+    """
+    result = MigrationResult()
+
+    if not legacy_path.exists():
+        result.legacy_not_found = True
+        return result
+
+    legacy_vars = parse_legacy_env(legacy_path)
+    if not legacy_vars:
+        return result
+
+    target_active = _parse_target_active_keys(target_path)
+
+    # Build list of vars to write
+    to_write: dict[str, str] = {}
+
+    for old_key, value in legacy_vars.items():
+        if old_key not in MAPPING:
+            result.warnings.append(f"Unknown key '{old_key}' in sdlc-config.env — not migrated")
+            continue
+
+        new_key = MAPPING[old_key]
+
+        if _is_placeholder(value):
+            result.skipped.append(old_key)
+            continue
+
+        # Check if target already has a real value for this key
+        existing = target_active.get(new_key, "")
+        if existing and not _is_placeholder(existing):
+            # Target has real value — do not overwrite
+            continue
+
+        to_write[new_key] = value
+        result.migrated.append(new_key)
+
+    if not to_write:
+        return result
+
+    # Backup existing target if it exists
+    if target_path.exists():
+        ts = str(int(time.time()))
+        backup = target_path.parent / f".env.bak.{ts}"
+        backup.write_text(target_path.read_text(encoding="utf-8"), encoding="utf-8")
+
+    # Read existing content (or start fresh)
+    if target_path.exists():
+        lines = target_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    else:
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        lines = []
+
+    # Update existing lines in-place where key exists with empty/placeholder value
+    updated_keys: set[str] = set()
+    new_lines: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            eq = stripped.find("=")
+            if eq > 0:
+                key = stripped[:eq].strip()
+                if key in to_write:
+                    new_lines.append(f"{key}={to_write[key]}\n")
+                    updated_keys.add(key)
+                    continue
+        new_lines.append(line if line.endswith("\n") else line + "\n")
+
+    # Append remaining keys not already in file
+    remaining = {k: v for k, v in to_write.items() if k not in updated_keys}
+    if remaining:
+        if new_lines and not new_lines[-1].strip() == "":
+            new_lines.append("\n")
+        new_lines.append("# --- Migrated from sdlc-config.env ---\n")
+        for key, val in remaining.items():
+            new_lines.append(f"{key}={val}\n")
+
+    # Atomic write via temp file
+    tmp_path = target_path.parent / ".env.tmp"
+    tmp_path.write_text("".join(new_lines), encoding="utf-8")
+    if os.name != "nt":
+        os.chmod(tmp_path, 0o600)
+    tmp_path.rename(target_path)
+
+    return result

package/skills/vds-skill/vds-scripts/vds_cli_common/tests/test_migrate_sdlc_config.py

@@ -0,0 +1,257 @@
+"""Unit tests for sdlc-config.env → .env migration."""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+import pytest
+
+
+# ── Fixtures ──
+
+
+@pytest.fixture
+def vds_dir(tmp_path: Path) -> Path:
+    """Create a temporary ~/.vds/ directory."""
+    d = tmp_path / ".vds"
+    d.mkdir()
+    return d
+
+
+@pytest.fixture
+def legacy_file(vds_dir: Path) -> Path:
+    """Create a populated sdlc-config.env."""
+    f = vds_dir / "sdlc-config.env"
+    f.write_text(
+        "# VDS Skill Pack — credential config\n"
+        "VDS_CONFLUENCE_TOKEN=my-confluence-pat\n"
+        "VDS_JIRA_TOKEN=my-jira-pat\n"
+        "VDS_BITBUCKET_TOKEN=my-bitbucket-pat\n"
+        "VDS_USERNAME=myuser\n"
+        "VDS_PASSWORD=mypass\n"
+        "VDS_CONFLUENCE_SPACE_DEFAULT=CEP\n"
+        "VDS_JIRA_PROJECT_DEFAULT=NTTC\n",
+        encoding="utf-8",
+    )
+    return f
+
+
+@pytest.fixture
+def target_file(vds_dir: Path) -> Path:
+    """Return path to target .env (does not create it)."""
+    return vds_dir / ".env"
+
+
+# ── Tests ──
+
+
+class TestParseEnvFile:
+    def test_basic_parse(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_text("KEY1=value1\nKEY2=value2\n")
+        result = parse_legacy_env(f)
+        assert result == {"KEY1": "value1", "KEY2": "value2"}
+
+    def test_skips_comments_and_blanks(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_text("# comment\n\nKEY=val\n  # indented comment\n")
+        result = parse_legacy_env(f)
+        assert result == {"KEY": "val"}
+
+    def test_handles_quoted_values(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_text('SINGLE=\'hello world\'\nDOUBLE="foo bar"\n')
+        result = parse_legacy_env(f)
+        assert result == {"SINGLE": "hello world", "DOUBLE": "foo bar"}
+
+    def test_handles_equals_in_value(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_text("TOKEN=abc123==\n")  # base64 padding
+        result = parse_legacy_env(f)
+        assert result == {"TOKEN": "abc123=="}
+
+    def test_handles_export_prefix(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_text("export KEY=val\n")
+        result = parse_legacy_env(f)
+        assert result == {"KEY": "val"}
+
+    def test_handles_crlf(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_bytes(b"KEY1=a\r\nKEY2=b\r\n")
+        result = parse_legacy_env(f)
+        assert result == {"KEY1": "a", "KEY2": "b"}
+
+    def test_handles_bom(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_bytes(b"\xef\xbb\xbfKEY=val\n")
+        result = parse_legacy_env(f)
+        assert result == {"KEY": "val"}
+
+    def test_nonexistent_file_returns_empty(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        result = parse_legacy_env(vds_dir / "nope.env")
+        assert result == {}
+
+    def test_skips_empty_values(self, vds_dir: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import parse_legacy_env
+
+        f = vds_dir / "test.env"
+        f.write_text("FILLED=ok\nEMPTY=\nALSO_EMPTY=  \n")
+        result = parse_legacy_env(f)
+        assert result == {"FILLED": "ok"}
+
+
+class TestMigration:
+    def test_basic_migration(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        result = migrate_sdlc_config(legacy_file, target_file)
+        assert result.migrated == [
+            "INTERNAL_CONFLUENCE_TOKEN",
+            "JIRA_TOKEN",
+            "BITBUCKET_TOKEN",
+            "VDS_USERNAME",
+            "VDS_PASSWORD",
+            "VDS_CONFLUENCE_SPACE_DEFAULT",
+            "VDS_JIRA_PROJECT_DEFAULT",
+        ]
+        assert result.skipped == []
+        assert result.warnings == []
+
+        # Verify file content
+        content = target_file.read_text(encoding="utf-8")
+        assert "INTERNAL_CONFLUENCE_TOKEN=my-confluence-pat" in content
+        assert "JIRA_TOKEN=my-jira-pat" in content
+        assert "BITBUCKET_TOKEN=my-bitbucket-pat" in content
+        assert "VDS_USERNAME=myuser" in content
+
+    def test_skips_placeholders(self, vds_dir: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        legacy = vds_dir / "sdlc-config.env"
+        legacy.write_text(
+            "VDS_CONFLUENCE_TOKEN=changeme\n"
+            "VDS_JIRA_TOKEN=<your-token>\n"
+            "VDS_BITBUCKET_TOKEN=xxx\n"
+            "VDS_USERNAME=realuser\n",
+        )
+        result = migrate_sdlc_config(legacy, target_file)
+        assert "VDS_USERNAME" in result.migrated
+        assert len(result.skipped) == 3
+        content = target_file.read_text(encoding="utf-8")
+        assert "VDS_USERNAME=realuser" in content
+        assert "INTERNAL_CONFLUENCE_TOKEN" not in content
+
+    def test_no_overwrite_existing_real_values(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        # Pre-populate target with a real value
+        target_file.write_text(
+            "INTERNAL_CONFLUENCE_TOKEN=already-set-by-user\n"
+            "JIRA_TOKEN=\n",  # empty — should be overwritten
+        )
+        result = migrate_sdlc_config(legacy_file, target_file)
+        content = target_file.read_text(encoding="utf-8")
+        # Real value preserved
+        assert "INTERNAL_CONFLUENCE_TOKEN=already-set-by-user" in content
+        # Empty value overwritten
+        assert "JIRA_TOKEN=my-jira-pat" in content
+
+    def test_overwrites_commented_var(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        target_file.write_text("# JIRA_TOKEN=old-commented-out\n")
+        result = migrate_sdlc_config(legacy_file, target_file)
+        content = target_file.read_text(encoding="utf-8")
+        assert "JIRA_TOKEN=my-jira-pat" in content
+
+    def test_idempotent(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        result1 = migrate_sdlc_config(legacy_file, target_file)
+        content_after_first = target_file.read_text(encoding="utf-8")
+        assert len(result1.migrated) == 7
+
+        result2 = migrate_sdlc_config(legacy_file, target_file)
+        content_after_second = target_file.read_text(encoding="utf-8")
+        assert result2.migrated == []
+        assert content_after_first == content_after_second
+
+    def test_warns_on_unknown_keys(self, vds_dir: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        legacy = vds_dir / "sdlc-config.env"
+        legacy.write_text("UNKNOWN_VAR=hello\nVDS_USERNAME=user\n")
+        result = migrate_sdlc_config(legacy, target_file)
+        assert "UNKNOWN_VAR" in result.warnings[0]
+        assert "VDS_USERNAME" in result.migrated
+
+    def test_creates_backup(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        target_file.write_text("EXISTING=value\n")
+        migrate_sdlc_config(legacy_file, target_file)
+        backups = list(target_file.parent.glob(".env.bak.*"))
+        assert len(backups) == 1
+        assert "EXISTING=value" in backups[0].read_text()
+
+    def test_no_backup_when_target_missing(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        assert not target_file.exists()
+        migrate_sdlc_config(legacy_file, target_file)
+        backups = list(target_file.parent.glob(".env.bak.*"))
+        assert len(backups) == 0
+
+    def test_file_permissions_0600(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        if os.name == "nt":
+            pytest.skip("Unix permissions not applicable on Windows")
+        migrate_sdlc_config(legacy_file, target_file)
+        mode = stat.S_IMODE(target_file.stat().st_mode)
+        assert mode == 0o600
+
+    def test_nonexistent_legacy_returns_skip(self, vds_dir: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        result = migrate_sdlc_config(vds_dir / "nope.env", target_file)
+        assert result.migrated == []
+        assert result.skipped == []
+        assert result.warnings == []
+        assert result.legacy_not_found is True
+
+    def test_preserves_existing_lines_and_comments(self, legacy_file: Path, target_file: Path) -> None:
+        from vds_cli_common.migrate_sdlc_config import migrate_sdlc_config
+
+        target_file.write_text(
+            "# My hand-written header\n"
+            "CUSTOM_VAR=keep-me\n"
+            "\n"
+            "# Another section\n"
+            "ANOTHER=also-keep\n",
+        )
+        migrate_sdlc_config(legacy_file, target_file)
+        content = target_file.read_text(encoding="utf-8")
+        assert "# My hand-written header" in content
+        assert "CUSTOM_VAR=keep-me" in content
+        assert "ANOTHER=also-keep" in content
+        assert "INTERNAL_CONFLUENCE_TOKEN=my-confluence-pat" in content