fix(installer): harden locale docs install

tests/lib/install-request.test.js

@@ -52,6 +52,29 @@ function runTests() {
     assert.deepStrictEqual(parsed.languages, []);
   })) passed++; else failed++;
 
+  if (test('parses --locale argument', () => {
+    const parsed = parseInstallArgs([
+      'node',
+      'scripts/install-apply.js',
+      '--locale', 'ja'
+    ]);
+
+    assert.strictEqual(parsed.locale, 'ja');
+    assert.deepStrictEqual(parsed.languages, []);
+  })) passed++; else failed++;
+
+  if (test('requires a --locale value', () => {
+    assert.throws(
+      () => parseInstallArgs([
+        'node',
+        'scripts/install-apply.js',
+        '--locale',
+        '--dry-run'
+      ]),
+      /Missing value for --locale/
+    );
+  })) passed++; else failed++;
+
   if (test('normalizes legacy language installs into a canonical request', () => {
     const request = normalizeInstallRequest({
       target: 'claude',
@@ -67,6 +90,69 @@ function runTests() {
     assert.strictEqual(request.profileId, null);
   })) passed++; else failed++;
 
+  if (test('normalizes locale-only installs as manifest component requests', () => {
+    const request = normalizeInstallRequest({
+      target: 'claude',
+      profileId: null,
+      moduleIds: [],
+      includeComponentIds: [],
+      excludeComponentIds: [],
+      languages: [],
+      locale: 'ja',
+    });
+
+    assert.strictEqual(request.mode, 'manifest');
+    assert.strictEqual(request.target, 'claude');
+    assert.deepStrictEqual(request.includeComponentIds, ['locale:ja']);
+    assert.deepStrictEqual(request.legacyLanguages, []);
+  })) passed++; else failed++;
+
+  if (test('allows legacy language installs to include a locale component', () => {
+    const request = normalizeInstallRequest({
+      target: 'claude',
+      profileId: null,
+      moduleIds: [],
+      includeComponentIds: [],
+      excludeComponentIds: [],
+      languages: ['typescript'],
+      locale: 'ja-JP',
+    });
+
+    assert.strictEqual(request.mode, 'legacy-compat');
+    assert.deepStrictEqual(request.legacyLanguages, ['typescript']);
+    assert.deepStrictEqual(request.includeComponentIds, ['locale:ja']);
+  })) passed++; else failed++;
+
+  if (test('rejects unsupported locale codes', () => {
+    assert.throws(
+      () => normalizeInstallRequest({
+        target: 'claude',
+        profileId: null,
+        moduleIds: [],
+        includeComponentIds: [],
+        excludeComponentIds: [],
+        languages: [],
+        locale: 'fr',
+      }),
+      /Unsupported locale/
+    );
+  })) passed++; else failed++;
+
+  if (test('rejects --locale for non-Claude targets', () => {
+    assert.throws(
+      () => normalizeInstallRequest({
+        target: 'cursor',
+        profileId: null,
+        moduleIds: [],
+        includeComponentIds: [],
+        excludeComponentIds: [],
+        languages: [],
+        locale: 'ja',
+      }),
+      /--locale can only be used with --target claude/
+    );
+  })) passed++; else failed++;
+
   if (test('normalizes manifest installs into a canonical request', () => {
     const request = normalizeInstallRequest({
       target: 'cursor',

tests/lib/locale-install.test.js

@@ -0,0 +1,172 @@
+/**
+ * Tests for --locale translated docs installs.
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const {
+  listInstallComponents,
+  resolveInstallPlan,
+} = require('../../scripts/lib/install-manifests');
+
+function normalizePlanPath(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function runInstallApply(args, options = {}) {
+  const scriptPath = path.join(__dirname, '..', '..', 'scripts', 'install-apply.js');
+  return execFileSync('node', [scriptPath, ...args], {
+    cwd: options.cwd || process.cwd(),
+    env: { ...process.env, ...(options.env || {}) },
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function runTests() {
+  console.log('\n=== Testing --locale translated docs installs ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('component catalog includes locale entries', () => {
+    const components = listInstallComponents({ family: 'locale' });
+    assert.ok(components.some(component => component.id === 'locale:ja'));
+    assert.ok(components.some(component => component.id === 'locale:zh-cn'));
+    assert.ok(components.every(component => component.family === 'locale'));
+  })) passed++; else failed++;
+
+  if (test('locale component resolves to the translated docs module', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-plan-'));
+    try {
+      const plan = resolveInstallPlan({
+        includeComponentIds: ['locale:ja'],
+        target: 'claude',
+        homeDir,
+      });
+
+      assert.deepStrictEqual(plan.selectedModuleIds, ['docs-ja-jp']);
+      assert.ok(
+        plan.operations.some(operation => (
+          normalizePlanPath(operation.sourceRelativePath) === 'docs/ja-JP'
+          && normalizePlanPath(operation.destinationPath).endsWith('/.claude/docs/ja-JP')
+        )),
+        'Should map docs/ja-JP to ~/.claude/docs/ja-JP'
+      );
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('end-to-end: --locale ja dry-run includes docs-ja-jp operations', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-dry-run-'));
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-dry-run-project-'));
+
+    try {
+      const output = runInstallApply([
+        '--locale', 'ja',
+        '--dry-run',
+        '--json',
+      ], {
+        cwd: projectDir,
+        env: { HOME: homeDir },
+      });
+      const json = JSON.parse(output);
+
+      assert.strictEqual(json.plan.mode, 'manifest');
+      assert.deepStrictEqual(json.plan.includedComponentIds, ['locale:ja']);
+      assert.deepStrictEqual(json.plan.selectedModuleIds, ['docs-ja-jp']);
+      assert.ok(
+        json.plan.operations.some(operation => (
+          normalizePlanPath(operation.sourceRelativePath) === 'docs/ja-JP/README.md'
+          && normalizePlanPath(operation.destinationPath).endsWith('/.claude/docs/ja-JP/README.md')
+        )),
+        'Should copy translated README into ~/.claude/docs/ja-JP'
+      );
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('end-to-end: legacy language plus --locale keeps legacy install and docs', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-legacy-dry-run-'));
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-legacy-dry-run-project-'));
+
+    try {
+      const output = runInstallApply([
+        'typescript',
+        '--locale', 'ja',
+        '--dry-run',
+        '--json',
+      ], {
+        cwd: projectDir,
+        env: { HOME: homeDir },
+      });
+      const json = JSON.parse(output);
+
+      assert.strictEqual(json.plan.mode, 'legacy-compat');
+      assert.deepStrictEqual(json.plan.legacyLanguages, ['typescript']);
+      assert.ok(json.plan.includedComponentIds.includes('locale:ja'));
+      assert.ok(json.plan.selectedModuleIds.includes('framework-language'));
+      assert.ok(json.plan.selectedModuleIds.includes('docs-ja-jp'));
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('end-to-end: --locale ja installs translated docs side-by-side', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-install-'));
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locale-install-project-'));
+
+    try {
+      runInstallApply([
+        '--locale', 'ja',
+      ], {
+        cwd: projectDir,
+        env: { HOME: homeDir },
+      });
+
+      const claudeRoot = path.join(homeDir, '.claude');
+      assert.ok(
+        fs.existsSync(path.join(claudeRoot, 'docs', 'ja-JP', 'README.md')),
+        'Should install Japanese README under docs/ja-JP'
+      );
+      assert.ok(
+        !fs.existsSync(path.join(claudeRoot, 'skills', 'ecc', 'configure-ecc', 'SKILL.md')),
+        'Locale-only install should not install English skills'
+      );
+
+      const statePath = path.join(claudeRoot, 'ecc', 'install-state.json');
+      const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      assert.deepStrictEqual(state.request.includeComponents, ['locale:ja']);
+      assert.deepStrictEqual(state.resolution.selectedModules, ['docs-ja-jp']);
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();