The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix(installer): harden locale docs install
Affaan Mustafa666b4e226157
diff --git a/manifests/install-components.json b/manifests/install-components.jsonindex 039d55cfd..0cc630a10 100644--- a/manifests/install-components.json+++ b/manifests/install-components.json@@ -531,31 +531,31 @@"family": "locale","description": "Japanese (ja-JP) translated reference docs installed to ~/.claude/docs/ja-JP/.","modules": [- "docs-ja-JP"+ "docs-ja-jp"]},{- "id": "locale:zh-CN",+ "id": "locale:zh-cn","family": "locale","description": "Simplified Chinese (zh-CN) translated reference docs installed to ~/.claude/docs/zh-CN/.","modules": [- "docs-zh-CN"+ "docs-zh-cn"]},{- "id": "locale:ko-KR",+ "id": "locale:ko-kr","family": "locale","description": "Korean (ko-KR) translated reference docs installed to ~/.claude/docs/ko-KR/.","modules": [- "docs-ko-KR"+ "docs-ko-kr"]},{- "id": "locale:pt-BR",+ "id": "locale:pt-br","family": "locale","description": "Brazilian Portuguese (pt-BR) translated reference docs installed to ~/.claude/docs/pt-BR/.","modules": [- "docs-pt-BR"+ "docs-pt-br"]},{@@ -575,19 +575,19 @@]},{- "id": "locale:vi-VN",+ "id": "locale:vi-vn","family": "locale","description": "Vietnamese (vi-VN) translated reference docs installed to ~/.claude/docs/vi-VN/.","modules": [- "docs-vi-VN"+ "docs-vi-vn"]},{- "id": "locale:zh-TW",+ "id": "locale:zh-tw","family": "locale","description": "Traditional Chinese (zh-TW) translated reference docs installed to ~/.claude/docs/zh-TW/.","modules": [- "docs-zh-TW"+ "docs-zh-tw"]}]diff --git a/manifests/install-modules.json b/manifests/install-modules.jsonindex 4cf7e7098..5f9c87541 100644--- a/manifests/install-modules.json+++ b/manifests/install-modules.json@@ -695,7 +695,7 @@"stability": "stable"},{- "id": "docs-ja-JP",+ "id": "docs-ja-jp","kind": "docs","description": "Japanese (ja-JP) translated reference docs for agents, commands, skills, and rules.","paths": [@@ -710,7 +710,7 @@"stability": "stable"},{- "id": "docs-zh-CN",+ "id": "docs-zh-cn","kind": "docs","description": "Simplified Chinese (zh-CN) translated reference docs for agents, commands, skills, and rules.","paths": [@@ -725,7 +725,7 @@"stability": "stable"},{- "id": "docs-ko-KR",+ "id": "docs-ko-kr","kind": "docs","description": "Korean (ko-KR) translated reference docs for agents, commands, skills, and rules.","paths": [@@ -740,7 +740,7 @@"stability": "stable"},{- "id": "docs-pt-BR",+ "id": "docs-pt-br","kind": "docs","description": "Brazilian Portuguese (pt-BR) translated reference docs for agents, commands, skills, and rules.","paths": [@@ -785,7 +785,7 @@"stability": "stable"},{- "id": "docs-vi-VN",+ "id": "docs-vi-vn","kind": "docs","description": "Vietnamese (vi-VN) translated reference docs for agents, commands, skills, and rules.","paths": [@@ -800,7 +800,7 @@"stability": "stable"},{- "id": "docs-zh-TW",+ "id": "docs-zh-tw","kind": "docs","description": "Traditional Chinese (zh-TW) translated reference docs for agents, commands, skills, and rules.","paths": [diff --git a/package.json b/package.jsonindex 72d9735db..af498b8f4 100644--- a/package.json+++ b/package.json@@ -56,6 +56,14 @@"agent.yaml","agents/","commands/",+ "docs/ja-JP/",+ "docs/ko-KR/",+ "docs/pt-BR/",+ "docs/ru/",+ "docs/tr/",+ "docs/vi-VN/",+ "docs/zh-CN/",+ "docs/zh-TW/","hooks/","install.ps1","install.sh",diff --git a/schemas/install-components.schema.json b/schemas/install-components.schema.jsonindex c77878dae..d72f41b06 100644--- a/schemas/install-components.schema.json+++ b/schemas/install-components.schema.json@@ -26,7 +26,7 @@"properties": {"id": {"type": "string",- "pattern": "^(baseline|lang|framework|capability|agent|skill):[a-z0-9-]+$"+ "pattern": "^(baseline|lang|framework|capability|agent|skill|locale):[a-z0-9-]+$"},"family": {"type": "string",@@ -36,7 +36,8 @@"framework","capability","agent",- "skill"+ "skill",+ "locale"]},"description": {diff --git a/schemas/install-modules.schema.json b/schemas/install-modules.schema.jsonindex 125733775..252f8e82c 100644--- a/schemas/install-modules.schema.json+++ b/schemas/install-modules.schema.json@@ -26,7 +26,8 @@"hooks","platform","orchestration",- "skills"+ "skills",+ "docs"]},"description": {diff --git a/scripts/ci/validate-install-manifests.js b/scripts/ci/validate-install-manifests.jsindex 26c4c5ad5..7f1f4f245 100644--- a/scripts/ci/validate-install-manifests.js+++ b/scripts/ci/validate-install-manifests.js@@ -21,6 +21,7 @@ const COMPONENT_FAMILY_PREFIXES = {language: 'lang:',framework: 'framework:',capability: 'capability:',+ locale: 'locale:',};function readJson(filePath, label) {@@ -163,9 +164,12 @@ function validateInstallManifests() {if (profiles.full) {const fullModules = new Set(profiles.full.modules);- for (const moduleId of moduleIds) {- if (!fullModules.has(moduleId)) {- console.error(`ERROR: full profile is missing module ${moduleId}`);+ for (const module of modules) {+ if (module.kind === 'docs' && module.defaultInstall === false) {+ continue;+ }+ if (!fullModules.has(module.id)) {+ console.error(`ERROR: full profile is missing module ${module.id}`);hasErrors = true;}}diff --git a/scripts/lib/install-executor.js b/scripts/lib/install-executor.jsindex d7a5e4eed..a8311fc1a 100644--- a/scripts/lib/install-executor.js+++ b/scripts/lib/install-executor.js@@ -555,6 +555,12 @@ function createLegacyCompatInstallPlan(options = {}) {const sourceRoot = options.sourceRoot || getSourceRoot();const projectRoot = options.projectRoot || process.cwd();const target = options.target || 'claude';+ const includeComponentIds = Array.isArray(options.includeComponentIds)+ ? [...options.includeComponentIds]+ : [];+ const excludeComponentIds = Array.isArray(options.excludeComponentIds)+ ? [...options.excludeComponentIds]+ : [];validateLegacyTarget(target);@@ -571,14 +577,14 @@ function createLegacyCompatInstallPlan(options = {}) {target,profileId: null,moduleIds: selection.moduleIds,- includeComponentIds: [],- excludeComponentIds: [],+ includeComponentIds,+ excludeComponentIds,legacyLanguages: selection.legacyLanguages,legacyMode: true,requestProfileId: null,requestModuleIds: [],- requestIncludeComponentIds: [],- requestExcludeComponentIds: [],+ requestIncludeComponentIds: includeComponentIds,+ requestExcludeComponentIds: excludeComponentIds,mode: 'legacy-compat',});}diff --git a/scripts/lib/install-manifests.js b/scripts/lib/install-manifests.jsindex 14e6769b6..c27d5e234 100644--- a/scripts/lib/install-manifests.js+++ b/scripts/lib/install-manifests.js@@ -18,17 +18,17 @@ const SUPPORTED_LOCALES = Object.freeze(['ja', 'zh-CN', 'ko-KR', 'pt-BR', 'ru',const LOCALE_ALIAS_TO_COMPONENT_ID = Object.freeze({'ja': 'locale:ja','ja-JP': 'locale:ja',- 'zh-CN': 'locale:zh-CN',- 'zh': 'locale:zh-CN',- 'ko-KR': 'locale:ko-KR',- 'ko': 'locale:ko-KR',- 'pt-BR': 'locale:pt-BR',- 'pt': 'locale:pt-BR',+ 'zh-CN': 'locale:zh-cn',+ 'zh': 'locale:zh-cn',+ 'ko-KR': 'locale:ko-kr',+ 'ko': 'locale:ko-kr',+ 'pt-BR': 'locale:pt-br',+ 'pt': 'locale:pt-br','ru': 'locale:ru','tr': 'locale:tr',- 'vi-VN': 'locale:vi-VN',- 'vi': 'locale:vi-VN',- 'zh-TW': 'locale:zh-TW',+ 'vi-VN': 'locale:vi-vn',+ 'vi': 'locale:vi-vn',+ 'zh-TW': 'locale:zh-tw',});function listSupportedLocales() {diff --git a/scripts/lib/install/request.js b/scripts/lib/install/request.jsindex 52a79e1ea..4cf5c0437 100644--- a/scripts/lib/install/request.js+++ b/scripts/lib/install/request.js@@ -62,7 +62,11 @@ function parseInstallArgs(argv) {}index += 1;} else if (arg === '--locale') {- parsed.locale = args[index + 1] || null;+ const locale = args[index + 1] || '';+ if (!locale || locale.startsWith('--')) {+ throw new Error('Missing value for --locale');+ }+ parsed.locale = locale;index += 1;} else if (arg === '--dry-run') {parsed.dryRun = true;@@ -85,6 +89,7 @@ function normalizeInstallRequest(options = {}) {? options.config: null;const profileId = options.profileId || config?.profileId || null;+ const target = options.target || config?.target || 'claude';const moduleIds = validateInstallModuleIds(dedupeStrings([...(config?.moduleIds || []), ...(options.moduleIds || [])]));@@ -95,9 +100,15 @@ function normalizeInstallRequest(options = {}) {`Unsupported locale: "${locale}". Supported locales: ${listSupportedLocales().join(', ')}`);}- const includeComponentIds = dedupeStrings([+ if (locale && target !== 'claude') {+ throw new Error('--locale can only be used with --target claude');+ }+ const requestedIncludeComponentIds = dedupeStrings([...(config?.includeComponentIds || []),...(options.includeComponentIds || []),+ ]);+ const includeComponentIds = dedupeStrings([+ ...requestedIncludeComponentIds,...(localeComponentId ? [localeComponentId] : []),]);const excludeComponentIds = dedupeStrings([@@ -108,13 +119,16 @@ function normalizeInstallRequest(options = {}) {...(Array.isArray(options.legacyLanguages) ? options.legacyLanguages : []),...(Array.isArray(options.languages) ? options.languages : []),]).map(language => language.toLowerCase()));- const target = options.target || config?.target || 'claude';const hasManifestBaseSelection = Boolean(profileId) || moduleIds.length > 0 || includeComponentIds.length > 0;+ const hasNonLocaleManifestSelection = Boolean(profileId)+ || moduleIds.length > 0+ || requestedIncludeComponentIds.length > 0+ || excludeComponentIds.length > 0;const usingManifestMode = hasManifestBaseSelection || excludeComponentIds.length > 0;- if (usingManifestMode && legacyLanguages.length > 0) {+ if (hasNonLocaleManifestSelection && legacyLanguages.length > 0) {throw new Error(- 'Legacy language arguments cannot be combined with --profile, --modules, --with, --without, --locale, or manifest config selections'+ 'Legacy language arguments cannot be combined with --profile, --modules, --with, --without, or manifest config selections');}@@ -123,7 +137,9 @@ function normalizeInstallRequest(options = {}) {}return {- mode: usingManifestMode ? 'manifest' : 'legacy-compat',+ mode: legacyLanguages.length > 0+ ? 'legacy-compat'+ : (usingManifestMode ? 'manifest' : 'legacy-compat'),target,profileId,moduleIds,diff --git a/scripts/lib/install/runtime.js b/scripts/lib/install/runtime.jsindex 91a340c86..55f55bfbd 100644--- a/scripts/lib/install/runtime.js+++ b/scripts/lib/install/runtime.js@@ -28,6 +28,8 @@ function createInstallPlanFromRequest(request, options = {}) {return createLegacyCompatInstallPlan({target: request.target,legacyLanguages: request.legacyLanguages,+ includeComponentIds: request.includeComponentIds,+ excludeComponentIds: request.excludeComponentIds,projectRoot: options.projectRoot,homeDir: options.homeDir,claudeRulesDir: options.claudeRulesDir,diff --git a/tests/lib/install-request.test.js b/tests/lib/install-request.test.jsindex 18e0ec37b..614c8ee26 100644--- a/tests/lib/install-request.test.js+++ b/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',diff --git a/tests/lib/locale-install.test.js b/tests/lib/locale-install.test.jsnew file mode 100644index 000000000..6e108b184--- /dev/null+++ b/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();