cowork-flow 2.3.0 → 2.4.0

package/src/commands/init.js

@@ -17,6 +17,14 @@ import {
   platformLabel
 } from '../lib/platforms.js';
 import { parseFlags, UsageError } from '../lib/cli-flags.js';
+import {
+  DEFAULT_LANGUAGE,
+  SUPPORTED_LANGUAGES,
+  normalizeLanguage,
+  readProjectLanguage,
+  withLanguage
+} from '../lib/language.js';
+import { templateRoot } from '../lib/paths.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -34,7 +42,7 @@ function parsePlatformSelectionOrUsage(values) {
 function parseInitArgs(args) {
   const { flags, positionals } = parseFlags(args, {
     boolean: ['--dry-run', '--force'],
-    value: ['--host', '--platform', '--platforms', '--developer'],
+    value: ['--host', '--platform', '--platforms', '--developer', '--language'],
     repeatable: ['--host', '--platform', '--platforms'],
     positional: { min: 0, max: 1, name: '[target]' }
   });
@@ -42,6 +50,7 @@ function parseInitArgs(args) {
     developer: flags['--developer'] ?? null,
     dryRun: Boolean(flags['--dry-run']),
     force: Boolean(flags['--force']),
+    language: flags['--language'] ?? null,
     platforms: [
       ...(flags['--host'] ?? []),
       ...(flags['--platform'] ?? []),
@@ -165,6 +174,104 @@ async function resolvePlatforms(options, selectPlatforms) {
   return parsePlatformSelectionOrUsage(selected);
 }
 
+function normalizeLanguageOrUsage(value) {
+  const language = normalizeLanguage(value);
+  if (!language) {
+    throw new UsageError(
+      `Unsupported language: ${value}. Supported: ${SUPPORTED_LANGUAGES.join(', ')}`
+    );
+  }
+  return language;
+}
+
+// An existing config is authoritative: the choice is never re-prompted or
+// rewritten, even by --force. A missing config prompts once, with zh-CN as the
+// default for both non-interactive and dry-run runs.
+async function resolveLanguage(options, prompt) {
+  const requested = options.language
+    ? normalizeLanguageOrUsage(options.language)
+    : null;
+  const existing = await readProjectLanguage(options.target);
+  if (existing.present) {
+    return {
+      existing: true,
+      configured: existing.configured,
+      language: existing.language,
+      valid: existing.valid,
+      raw: existing.raw,
+      requested,
+      source: 'existing'
+    };
+  }
+
+  if (requested) {
+    return {
+      existing: false,
+      language: requested,
+      requested,
+      source: 'flag'
+    };
+  }
+
+  if (options.dryRun || typeof prompt !== 'function') {
+    return {
+      existing: false,
+      language: DEFAULT_LANGUAGE,
+      requested,
+      source: 'default'
+    };
+  }
+
+  const answer = String(
+    await prompt(`Project language (${SUPPORTED_LANGUAGES.join('/')}) [${DEFAULT_LANGUAGE}]: `) ?? ''
+  ).trim();
+  return {
+    existing: false,
+    language: normalizeLanguageOrUsage(answer || DEFAULT_LANGUAGE),
+    requested,
+    source: answer ? 'prompt' : 'default'
+  };
+}
+
+function emitLanguageWarnings(io, language) {
+  if (!language.existing) {
+    return;
+  }
+  if (!language.valid) {
+    io.writeErr(
+      `Warning: unsupported language ${JSON.stringify(language.raw)} in .cowork-flow/config.yaml; using ${language.language}. Edit the file to change it.\n`
+    );
+    return;
+  }
+  if (language.requested && !language.configured) {
+    io.writeErr(
+      `Warning: .cowork-flow/config.yaml has no language setting; using ${language.language}. Add language: ${language.requested} and run cwf project sync to switch.\n`
+    );
+    return;
+  }
+  if (language.requested && language.requested !== language.language) {
+    io.writeErr(
+      `Warning: existing .cowork-flow/config.yaml language ${language.language} wins over --language ${language.requested}.\n`
+    );
+  }
+}
+
+async function buildConfigActions(target, language, existing) {
+  if (existing) {
+    return [];
+  }
+  const source = join(templateRoot, '.cowork-flow', 'config.yaml');
+  const content = withLanguage(await readFile(source, 'utf8'), language);
+  return [{
+    action: 'create',
+    source,
+    destination: join(target, '.cowork-flow', 'config.yaml'),
+    relativePath: '.cowork-flow/config.yaml',
+    content,
+    targetExists: false
+  }];
+}
+
 
 async function buildDeveloperActions(target, developer) {
   const workflowDir = join(target, '.cowork-flow');
@@ -195,14 +302,22 @@ export async function runInitWithOptions(
 ) {
   const options = parseInitArgs(args);
   const platforms = await resolvePlatforms(options, selectPlatforms);
+  const language = await resolveLanguage(options, prompt);
+  emitLanguageWarnings(io, language);
   const developer = await resolveDeveloperName(options, prompt);
   const packageInfo = await readPackageInfo();
   const developerActions = developer.name
     ? await buildDeveloperActions(options.target, developer)
     : [];
+  const configActions = await buildConfigActions(
+    options.target,
+    language.language,
+    language.existing
+  );
   const plan = await buildInitPlan(options.target, {
-    additionalActions: developerActions,
+    additionalActions: [...developerActions, ...configActions],
     force: options.force,
+    language: language.language,
     platforms,
     version: packageInfo.version
   });
@@ -220,6 +335,11 @@ export async function runInitWithOptions(
     } else {
       io.writeOut('dry-run would-skip=.cowork-flow/.developer (no developer identity; pass --developer)\n');
     }
+    if (language.existing) {
+      io.writeOut(`dry-run preserve-existing=.cowork-flow/config.yaml for language ${language.language}\n`);
+    } else {
+      io.writeOut(`dry-run would-create=.cowork-flow/config.yaml for language ${language.language}\n`);
+    }
     io.writeOut('Next: update AGENTS.md and .cowork-flow/config.yaml for this project.\n');
     return 0;
   }
@@ -230,6 +350,13 @@ export async function runInitWithOptions(
     const source = developer.source === 'git' ? ' (from git user.name)' : '';
     io.writeOut(`Developer initialized: ${developer.name}${source}\n`);
   }
+  if (language.existing) {
+    const missing = language.configured ? '' : ' (default; no language key)';
+    io.writeOut(`Language already initialized: ${language.language}${missing}\n`);
+  } else {
+    const source = language.source === 'default' ? ' (default)' : '';
+    io.writeOut(`Language initialized: ${language.language}${source}\n`);
+  }
   io.writeOut('Next: update AGENTS.md and .cowork-flow/config.yaml for this project.\n');
   return 0;
 }

package/src/commands/registry.js

@@ -51,18 +51,20 @@ export const COMMANDS = [
   {
     path: ['project', 'init'],
     summary: 'Copy the cowork-flow template into a project',
-    usage: `project init [target] --host <${HOST_TOKENS}> [--developer <name>] [--dry-run] [--force]`,
+    usage: `project init [target] --host <${HOST_TOKENS}> [--developer <name>] [--language <zh-CN|en-US>] [--dry-run] [--force]`,
     flags: [
       { name: '--host', kind: 'value', valueName: 'host', repeatable: true, description: 'Host to set the project up for; repeatable and comma-separated, auto-detected when omitted' },
       { name: '--platform', kind: 'value', valueName: 'host', repeatable: true, description: 'Alias of --host' },
       { name: '--platforms', kind: 'value', valueName: 'host', repeatable: true, description: 'Alias of --host' },
       { name: '--developer', kind: 'value', valueName: 'name', description: 'Developer name recorded in .cowork-flow/.developer; falls back to git user.name' },
+      { name: '--language', kind: 'value', valueName: 'language', description: 'Output language for task and plan artifacts; accepts zh-CN or en-US (default: zh-CN)' },
       flag('--dry-run'),
       flag('--force')
     ],
     positional: { min: 0, max: 1, name: '[target]' },
     examples: [
       'cwf project init --host codex --developer alice',
+      'cwf project init --host codex --developer alice --language en-US',
       'cwf project init ./my-project --host all --dry-run'
     ],
     run: (args, context) => runInit(args, context)

package/src/commands/source-refresh.js

@@ -9,6 +9,7 @@ import {
   formatReadinessReport,
   summarizePlan
 } from '../lib/copy-template.js';
+import { readProjectLanguageStrict } from '../lib/language.js';
 
 import { parseFlags } from '../lib/cli-flags.js';
 
@@ -25,7 +26,10 @@ function parseSourceRefreshArgs(args) {
 
 export async function runSourceRefresh(args, { io, fileSystem } = {}) {
   const options = parseSourceRefreshArgs(args);
-  const plan = await buildSourceCheckoutRefreshPlan(options.target);
+  const language = await readProjectLanguageStrict(options.target);
+  const plan = await buildSourceCheckoutRefreshPlan(options.target, {
+    language: language.language
+  });
 
   await applyPlan(plan, { dryRun: options.dryRun, fileSystem });
   io.writeOut(summarizePlan(plan, options.dryRun));

package/src/commands/sync.js

@@ -12,6 +12,7 @@ import {
 } from '../lib/copy-template.js';
 import { readPackageInfo } from '../lib/package-info.js';
 import { formatPlatformList } from '../lib/platforms.js';
+import { readProjectLanguageStrict } from '../lib/language.js';
 import { parseFlags } from '../lib/cli-flags.js';
 
 function parseSyncArgs(args) {
@@ -29,9 +30,11 @@ function parseSyncArgs(args) {
 export async function runSync(args, { io, fileSystem }) {
   const options = parseSyncArgs(args);
   const packageInfo = await readPackageInfo();
+  const language = await readProjectLanguageStrict(options.target);
   const platforms = await detectInstalledPlatforms(options.target);
   const plan = await buildSyncPlan(options.target, {
     force: options.force,
+    language: language.language,
     platforms,
     version: packageInfo.version
   });

package/src/lib/copy-template.js

@@ -153,13 +153,17 @@ async function appendSkillReadRootActions(actions, {
   }
 }
 
+// The source checkout's `.cowork-flow/spec` tree is a mirror of the template,
+// not a downstream project's spec tree: project-owned directories are framework
+// content here too, so dev refresh rewrites every spec directory and keeps only
+// task/plan state and the project config protected.
 function isSourceCheckoutProtected(relativePath) {
   const normalized = toTemplatePath(relativePath);
   if (hostRegistry.syncPolicy.protectedFiles.includes(normalized)) {
     return true;
   }
   return hostRegistry.syncPolicy.protectedPrefixes
-    .filter((prefix) => prefix !== '.cowork-flow/spec/')
+    .filter((prefix) => !prefix.startsWith('.cowork-flow/spec/'))
     .some((prefix) => normalized.startsWith(prefix))
     || normalized.startsWith('.cowork-flow/.runtime/');
 }
@@ -196,12 +200,16 @@ export async function buildInitPlan(targetDir, options = {}) {
       continue;
     }
 
-    const source = join(templateRoot, file);
+    const source = join(
+      templateRoot,
+      ...hostRegistry.localizedSource(templatePath, options.language).split('/')
+    );
     const destination = join(targetDir, file);
     seen.add(destination);
     const exists = await pathExists(destination);
+    const forceProtected = hostRegistry.isForceProtectedSyncFile(templatePath);
     const action = exists
-      ? (options.force && templatePath !== '.cowork-flow/.developer' ? 'update' : 'skip')
+      ? (forceProtected ? 'protected' : (options.force && templatePath !== '.cowork-flow/.developer' ? 'update' : 'skip'))
       : 'create';
     actions.push({ action, source, destination, relativePath: file });
   }
@@ -448,7 +456,10 @@ export async function buildSourceCheckoutRefreshPlan(targetDir, options = {}) {
     if (!shouldIncludeSourceCheckoutRuntimeFile(templatePath)) {
       continue;
     }
-    const source = join(templateRoot, file);
+    const source = join(
+      templateRoot,
+      ...hostRegistry.localizedSource(templatePath, options.language).split('/')
+    );
     const destination = join(targetDir, file);
     seen.add(destination);
     const exists = await pathExists(destination);
@@ -508,12 +519,19 @@ async function planSyncFile(file, { targetDir, options, platforms, seen }) {
     return null;
   }
 
-  const source = join(templateRoot, file);
+  const source = join(
+    templateRoot,
+    ...hostRegistry.localizedSource(file, options.language).split('/')
+  );
   const exists = await pathExists(destination);
   if (hostRegistry.isManagedBlockFile(file)) {
     return await buildManagedBlockSyncAction({ source, destination, exists, options, relativePath: file });
   }
 
+  if (exists && hostRegistry.isForceProtectedSyncFile(file)) {
+    return { action: 'protected', source, destination, relativePath: file };
+  }
+
   const protectedFile = hostRegistry.isProtectedSyncFile(file) && !options.force && exists;
   const safeFile = hostRegistry.isSafeSyncFile(file);
 

package/src/lib/host-assets.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { packageRoot, templateRoot } from './paths.js';
@@ -37,6 +37,7 @@ const MANIFEST_KEYS = [
   'capabilityMatrix',
   'platforms',
   'excludedPrefixes',
+  'localization',
   'syncPolicy'
 ];
 const PLATFORM_KEYS = [
@@ -57,6 +58,7 @@ const SKILL_DISCOVERY_KEYS = ['scope', 'evidence', 'path', 'gates'];
 const SKILL_DISCOVERY_SCOPES = ['project'];
 const SYNC_POLICY_KEYS = [
   'protectedFiles',
+  'forceProtectedFiles',
   'protectedPrefixes',
   'safeFiles',
   'safePrefixes',
@@ -101,6 +103,7 @@ function aliasIndex(platforms) {
 function normalizedSyncPolicy(policy) {
   return {
     protectedFiles: policy.protectedFiles.map(normalizePath),
+    forceProtectedFiles: (policy.forceProtectedFiles ?? []).map(normalizePath),
     protectedPrefixes: policy.protectedPrefixes.map(normalizePath),
     safeFiles: policy.safeFiles.map(normalizePath),
     safePrefixes: policy.safePrefixes.map(normalizePath),
@@ -110,6 +113,27 @@ function normalizedSyncPolicy(policy) {
 }
 
 
+// A manifest without localization keeps every asset in the base template, which
+// is exactly the pre-localization behaviour.
+function normalizedLocalization(localization) {
+  const raw = localization ?? {
+    default: 'zh-CN',
+    supported: ['zh-CN', 'en-US'],
+    assets: {}
+  };
+  return {
+    default: raw.default,
+    supported: [...raw.supported],
+    assets: Object.fromEntries(
+      Object.entries(raw.assets).map(([language, assets]) => [
+        language,
+        assets.map(normalizePath)
+      ])
+    )
+  };
+}
+
+
 // Every lookup a registry closes over, built after the
 // manifest passes validation. The order here is the order
 // init/sync observe.
@@ -120,6 +144,7 @@ function buildHostIndex(manifest) {
   const aliases = aliasIndex(platforms);
   const platformIds = platforms.map((platform) => platform.id);
   const capabilityMatrix = normalizeCapabilityMatrix(manifest.capabilityMatrix);
+  const localization = normalizedLocalization(manifest.localization);
   const syncPolicy = normalizedSyncPolicy(manifest.syncPolicy);
   const assetPrefixes = unique(
     platforms.flatMap((platform) => platform.assetPrefixes)
@@ -140,10 +165,12 @@ function buildHostIndex(manifest) {
     aliases,
     platformIds,
     capabilityMatrix,
+    localization,
     syncPolicy,
     assetPrefixes,
     skillReadRoots,
     protectedFiles: new Set(syncPolicy.protectedFiles),
+    forceProtectedFiles: new Set(syncPolicy.forceProtectedFiles),
     safeFiles: new Set(syncPolicy.safeFiles),
     managedBlockFiles: new Set(syncPolicy.managedBlockFiles)
   };
@@ -226,6 +253,7 @@ function syncRules(index) {
   const {
     syncPolicy,
     protectedFiles,
+    forceProtectedFiles,
     safeFiles,
     managedBlockFiles,
     assetPrefixes,
@@ -250,6 +278,12 @@ function syncRules(index) {
       || syncPolicy.protectedPrefixes.some((prefix) => normalized.startsWith(prefix));
   }
 
+  // A force-protected file is created once and never replaced, even by
+  // `init --force` or `sync --force`.
+  function isForceProtectedSyncFile(relativePath) {
+    return forceProtectedFiles.has(normalizePath(relativePath));
+  }
+
   function isManagedBlockFile(relativePath) {
     return managedBlockFiles.has(normalizePath(relativePath));
   }
@@ -267,7 +301,13 @@ function syncRules(index) {
     });
   }
 
-  return { isSafeSyncFile, isProtectedSyncFile, isManagedBlockFile, obsoleteSyncFiles };
+  return {
+    isSafeSyncFile,
+    isProtectedSyncFile,
+    isForceProtectedSyncFile,
+    isManagedBlockFile,
+    obsoleteSyncFiles
+  };
 }
 
 
@@ -298,6 +338,7 @@ export function createHostRegistry(manifest) {
     platforms: index.platforms,
     platformIds: index.platformIds,
     capabilityMatrix: index.capabilityMatrix,
+    localization: index.localization,
     syncPolicy: index.syncPolicy,
     assetPrefixes: index.assetPrefixes,
     skillReadRoots: index.skillReadRoots,
@@ -323,6 +364,27 @@ export function createHostRegistry(manifest) {
     skillDestination(platformId) {
       return index.byId.get(platformId)?.skillReadRoot ?? null;
     },
+    // Canonical project-relative path for the asset's source. Non-default
+    // languages resolve only declared assets; everything else stays on the
+    // base template.
+    localizedSource(relativePath, language) {
+      const normalized = normalizePath(relativePath);
+      const selected = language ?? index.localization.default;
+      if (!index.localization.supported.includes(selected)) {
+        throw new Error(
+          `Unsupported language: ${selected}. Supported: ${index.localization.supported.join(', ')}`
+        );
+      }
+      const assets = index.localization.assets[selected] ?? [];
+      if (!assets.includes(normalized)) {
+        return normalized;
+      }
+      const localized = `locales/${selected}/${normalized}`;
+      if (!existsSync(join(templateRoot, ...localized.split('/')))) {
+        throw new Error(`Missing localized asset: ${localized}`);
+      }
+      return localized;
+    },
     // A declaration names a directory inside the package;
     // the absolute source dir is resolved once, here.
     platformPayload(platformId) {
@@ -337,6 +399,7 @@ export function createHostRegistry(manifest) {
     },
     isSafeSyncFile: sync.isSafeSyncFile,
     isProtectedSyncFile: sync.isProtectedSyncFile,
+    isForceProtectedSyncFile: sync.isForceProtectedSyncFile,
     isManagedBlockFile: sync.isManagedBlockFile,
     obsoleteSyncFiles: sync.obsoleteSyncFiles
   };
@@ -378,10 +441,59 @@ function validateManifest(manifest) {
     manifest.excludedPrefixes,
     'Host Asset Manifest excludedPrefixes'
   );
+  validateLocalization(manifest.localization);
   validateCapabilityMatrix(manifest.capabilityMatrix, allowed, platformIds);
   validateSyncPolicy(manifest.syncPolicy);
 }
 
+function validateLocalization(localization) {
+  if (localization === undefined) {
+    return;
+  }
+  if (!localization || typeof localization !== 'object' || Array.isArray(localization)) {
+    throw new Error('Host Asset Manifest localization must be an object');
+  }
+  assertKnownKeys(
+    localization,
+    ['default', 'supported', 'assets'],
+    'Host Asset Manifest localization'
+  );
+  validateRequiredString(
+    localization.default,
+    'Host Asset Manifest localization.default'
+  );
+  validateStringArray(
+    localization.supported,
+    'Host Asset Manifest localization.supported',
+    { unique: true }
+  );
+  if (!localization.supported.includes(localization.default)) {
+    throw new Error(
+      'Host Asset Manifest localization.default must be listed in localization.supported'
+    );
+  }
+  if (!localization.assets || typeof localization.assets !== 'object' || Array.isArray(localization.assets)) {
+    throw new Error('Host Asset Manifest localization.assets must be an object');
+  }
+  for (const [language, assets] of Object.entries(localization.assets)) {
+    if (!localization.supported.includes(language)) {
+      throw new Error(
+        `Host Asset Manifest localization.assets language is not supported: ${language}`
+      );
+    }
+    if (language === localization.default) {
+      throw new Error(
+        'Host Asset Manifest localization.assets must not override the default language'
+      );
+    }
+    validateStringArray(
+      assets,
+      `Host Asset Manifest localization.assets.${language}`,
+      { unique: true }
+    );
+  }
+}
+
 function validateCapabilityValues(values) {
   validateStringArray(
     values,
@@ -515,6 +627,9 @@ function validateSyncPolicy(syncPolicy) {
   }
   assertKnownKeys(syncPolicy, SYNC_POLICY_KEYS, 'Host Asset Manifest syncPolicy');
   for (const key of SYNC_POLICY_KEYS) {
+    if (key === 'forceProtectedFiles' && syncPolicy[key] === undefined) {
+      continue;
+    }
     validateStringArray(
       syncPolicy[key],
       `Host Asset Manifest syncPolicy.${key}`