cowork-flow 1.6.0 → 1.7.2

package/src/cli.js

@@ -2,32 +2,19 @@ import { stdin as input, stdout as output } from 'node:process';
 import { emitKeypressEvents } from 'node:readline';
 import { createInterface } from 'node:readline/promises';
 
-import { runInit } from './commands/init.js';
-import { runInstallDshHook } from './commands/install-dsh-hook.js';
-import { runInstallDshPreset } from './commands/install-dsh-preset.js';
-import { runInstallKimiHook } from './commands/install-kimi-hook.js';
-import { runInstallZCodePlugin } from './commands/install-zcode-plugin.js';
-import { runMcpState } from './commands/mcp-state.js';
-import { runSourceRefresh } from './commands/source-refresh.js';
-import { runSync } from './commands/sync.js';
-import { runUpdate } from './commands/update.js';
+import { UsageError } from './lib/cli-flags.js';
 import { readPackageInfo } from './lib/package-info.js';
-
-const HELP = `cowork-flow
-
-Usage:
-  cowork-flow init [target] --platform <codex|opencode|claude-code|all> [--developer <name>] [--dry-run] [--force]
-  cowork-flow install-zcode-plugin [--dry-run] [--force] [--prune-old]
-  cowork-flow install-dsh-preset [--dry-run] [--force]
-  cowork-flow install-dsh-hook [--dry-run] [--force] [--uninstall]
-  cowork-flow install-kimi-hook [--dry-run] [--force] [--uninstall]
-  cowork-flow update
-  cowork-flow sync [target] [--dry-run] [--force]
-  cowork-flow source-refresh [target] [--dry-run]
-  cowork-flow mcp-state
-  cowork-flow --version
-  cowork-flow --help
-`;
+import {
+  aliasNotice,
+  groupFor,
+  helpPath,
+  renderHelp,
+  resolve
+} from './commands/registry.js';
+
+// A usage error is the caller's mistake and gets its own
+// exit code; a failed operation stays 1. Success is 0.
+export const EXIT_USAGE = 2;
 
 function defaultIo() {
   return {
@@ -52,55 +39,99 @@ async function defaultPrompt(message) {
   }
 }
 
-async function defaultSelectPlatforms({ message, choices, defaultSelected = [] }) {
-  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
-    return null;
-  }
 
-  const selected = new Set(defaultSelected);
-  let activeIndex = 0;
-  let search = '';
-  let renderedLines = 0;
+function matchingChoices(choices, search) {
+  const term = search.toLowerCase();
+  return choices.filter((choice) => choice.label.toLowerCase().includes(term));
+}
+
 
-  const filteredChoices = () => {
-    const term = search.toLowerCase();
-    return choices.filter((choice) => choice.label.toLowerCase().includes(term));
-  };
+function pickerLines(state, { message, choices }) {
+  const visibleChoices = matchingChoices(choices, state.search);
+  if (state.activeIndex >= visibleChoices.length) {
+    state.activeIndex = Math.max(0, visibleChoices.length - 1);
+  }
 
-  const render = () => {
-    const visibleChoices = filteredChoices();
-    if (activeIndex >= visibleChoices.length) {
-      activeIndex = Math.max(0, visibleChoices.length - 1);
+  const selectedLabels = choices
+    .filter((choice) => state.selected.has(choice.value))
+    .map((choice) => choice.label);
+  const lines = [
+    `? ${message} (${choices.length} available)`,
+    `Selected: ${selectedLabels.length > 0 ? selectedLabels.join(', ') : '(none)'}`,
+    `Search: ${state.search || '[type to filter]'}`,
+    '↑↓ navigate • Space toggle • Backspace remove • Enter confirm'
+  ];
+
+  if (visibleChoices.length === 0) {
+    lines.push('  (no matches)');
+  } else {
+    for (let index = 0; index < visibleChoices.length; index += 1) {
+      const choice = visibleChoices[index];
+      const cursor = index === state.activeIndex ? '›' : ' ';
+      const marker = state.selected.has(choice.value) ? '◉' : '○';
+      const suffix = state.selected.has(choice.value) ? ' (selected)' : '';
+      lines.push(`${cursor} ${marker} ${choice.label}${suffix}`);
     }
+  }
+  return lines;
+}
 
-    if (renderedLines > 0) {
-      output.write(`\x1b[${renderedLines}A\x1b[0J`);
-    }
 
-    const selectedLabels = choices
-      .filter((choice) => selected.has(choice.value))
-      .map((choice) => choice.label);
-    const lines = [
-      `? ${message} (${choices.length} available)`,
-      `Selected: ${selectedLabels.length > 0 ? selectedLabels.join(', ') : '(none)'}`,
-      `Search: ${search || '[type to filter]'}`,
-      '↑↓ navigate • Space toggle • Backspace remove • Enter confirm'
-    ];
-
-    if (visibleChoices.length === 0) {
-      lines.push('  (no matches)');
+function drawPicker(state, { message, choices }) {
+  const lines = pickerLines(state, { message, choices });
+  if (state.renderedLines > 0) {
+    output.write(`\x1b[${state.renderedLines}A\x1b[0J`);
+  }
+  output.write(`${lines.join('\n')}\n`);
+  state.renderedLines = lines.length;
+}
+
+
+// Returns a cancel/confirm outcome, or null for "mutated,
+// redraw".
+function applyPickerKey(state, text, key, choices) {
+  const visibleChoices = matchingChoices(choices, state.search);
+  if (key.ctrl && key.name === 'c') {
+    return { outcome: 'cancel' };
+  }
+  if (key.name === 'return' || key.name === 'enter') {
+    if (state.selected.size === 0 && visibleChoices[state.activeIndex]) {
+      state.selected.add(visibleChoices[state.activeIndex].value);
+    }
+    return { outcome: 'confirm', value: [...state.selected] };
+  }
+  if (key.name === 'up') {
+    state.activeIndex = Math.max(0, state.activeIndex - 1);
+  } else if (key.name === 'down') {
+    state.activeIndex = Math.min(Math.max(visibleChoices.length - 1, 0), state.activeIndex + 1);
+  } else if (key.name === 'space' && visibleChoices[state.activeIndex]) {
+    const value = visibleChoices[state.activeIndex].value;
+    if (state.selected.has(value)) {
+      state.selected.delete(value);
     } else {
-      for (let index = 0; index < visibleChoices.length; index += 1) {
-        const choice = visibleChoices[index];
-        const cursor = index === activeIndex ? '›' : ' ';
-        const marker = selected.has(choice.value) ? '◉' : '○';
-        const suffix = selected.has(choice.value) ? ' (selected)' : '';
-        lines.push(`${cursor} ${marker} ${choice.label}${suffix}`);
-      }
+      state.selected.add(value);
     }
+  } else if (key.name === 'backspace') {
+    state.search = state.search.slice(0, -1);
+    state.activeIndex = 0;
+  } else if (text && text.trim() && text.length === 1) {
+    state.search += text;
+    state.activeIndex = 0;
+  }
+  return null;
+}
+
+
+async function defaultSelectPlatforms({ message, choices, defaultSelected = [] }) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
+    return null;
+  }
 
-    output.write(`${lines.join('\n')}\n`);
-    renderedLines = lines.length;
+  const state = {
+    selected: new Set(defaultSelected),
+    activeIndex: 0,
+    search: '',
+    renderedLines: 0
   };
 
   return await new Promise((resolve, reject) => {
@@ -115,106 +146,75 @@ async function defaultSelectPlatforms({ message, choices, defaultSelected = [] }
     };
 
     const onKeypress = (text, key = {}) => {
-      const visibleChoices = filteredChoices();
-      if (key.ctrl && key.name === 'c') {
+      const action = applyPickerKey(state, text, key, choices);
+      if (action?.outcome === 'cancel') {
         cleanup();
         reject(new Error('Platform selection cancelled'));
         return;
       }
-      if (key.name === 'return' || key.name === 'enter') {
-        if (selected.size === 0 && visibleChoices[activeIndex]) {
-          selected.add(visibleChoices[activeIndex].value);
-        }
+      if (action?.outcome === 'confirm') {
         cleanup();
-        resolve([...selected]);
+        resolve(action.value);
         return;
       }
-      if (key.name === 'up') {
-        activeIndex = Math.max(0, activeIndex - 1);
-      } else if (key.name === 'down') {
-        activeIndex = Math.min(Math.max(visibleChoices.length - 1, 0), activeIndex + 1);
-      } else if (key.name === 'space' && visibleChoices[activeIndex]) {
-        const value = visibleChoices[activeIndex].value;
-        if (selected.has(value)) {
-          selected.delete(value);
-        } else {
-          selected.add(value);
-        }
-      } else if (key.name === 'backspace') {
-        search = search.slice(0, -1);
-        activeIndex = 0;
-      } else if (text && text.trim() && text.length === 1) {
-        search += text;
-        activeIndex = 0;
-      }
-      render();
+      drawPicker(state, { message, choices });
     };
 
     input.on('keypress', onKeypress);
-    render();
+    drawPicker(state, { message, choices });
   });
 }
 
+
 export async function main(argv = process.argv.slice(2), options = {}) {
   const io = options.io ?? defaultIo();
   const prompt = Object.hasOwn(options, 'prompt') ? options.prompt : defaultPrompt;
   const selectPlatforms = Object.hasOwn(options, 'selectPlatforms')
     ? options.selectPlatforms
     : defaultSelectPlatforms;
-  const [command, ...args] = argv;
 
   try {
-    if (!command || command === '--help' || command === '-h') {
-      io.writeOut(HELP);
+    // Asking for help is an explicit intent that outranks
+    // everything else in argv, so it is answered before
+    // any command is resolved.
+    if (argv.includes('--help') || argv.includes('-h')) {
+      io.writeOut(renderHelp(helpPath(argv)));
       return 0;
     }
 
-    if (command === '--version' || command === '-v') {
-      const packageInfo = await readPackageInfo();
-      io.writeOut(`${packageInfo.version}\n`);
+    if (argv.length === 0) {
+      io.writeOut(renderHelp([]));
       return 0;
     }
 
-    if (command === 'init') {
-      return await runInit(args, { io, prompt, selectPlatforms });
-    }
-
-    if (command === 'sync') {
-      return await runSync(args, { io });
-    }
-
-    if (command === 'source-refresh') {
-      return await runSourceRefresh(args, { io });
-    }
-
-    if (command === 'update') {
-      return await runUpdate(args, { io });
-    }
-
-    if (command === 'install-zcode-plugin') {
-      return await runInstallZCodePlugin(args);
-    }
-
-    if (command === 'install-dsh-preset') {
-      return await runInstallDshPreset(args);
+    if (argv[0] === '--version' || argv[0] === '-v') {
+      const packageInfo = await readPackageInfo();
+      io.writeOut(`${packageInfo.version}\n`);
+      return 0;
     }
 
-    if (command === 'install-dsh-hook') {
-      return await runInstallDshHook(args);
+    if (argv[0] === 'help') {
+      io.writeOut(renderHelp(helpPath(argv)));
+      return 0;
     }
 
-    if (command === 'install-kimi-hook') {
-      return await runInstallKimiHook(args);
+    // A bare group names no action: answer with that
+    // group's commands instead of an error, which is what
+    // the caller wants anyway.
+    if (argv.length === 1 && groupFor(argv[0])) {
+      io.writeOut(renderHelp([argv[0]]));
+      return 0;
     }
 
-    if (command === 'mcp-state') {
-      return await runMcpState(args);
+    const { command, args, alias } = resolve(argv);
+    if (alias !== null && !alias.permanent) {
+      io.writeErr(aliasNotice(alias));
     }
-
-    io.writeErr(`Unknown command: ${command}\n`);
-    return 1;
+    // Installers that finish quietly return nothing;
+    // `main` always answers with an exit code.
+    return (await command.run(args, { io, prompt, selectPlatforms })) ?? 0;
   } catch (error) {
     io.writeErr(`${error instanceof Error ? error.message : String(error)}\n`);
-    return 1;
+    return error instanceof UsageError ? EXIT_USAGE : 1;
   }
 }

package/src/commands/host.js

@@ -0,0 +1,182 @@
+import { join, resolve } from 'node:path';
+
+import { UsageError, extractValueFlag, parseFlags } from '../lib/cli-flags.js';
+import { hostRegistry } from '../lib/host-assets.js';
+import { pathExists } from '../lib/install-support.js';
+import { runInstallCodexPlugin, FLAGS as CODEX_PLUGIN_FLAGS } from './install-codex-plugin.js';
+import { runInstallClaudeCodePlugin, FLAGS as CLAUDE_CODE_PLUGIN_FLAGS } from './install-claude-code-plugin.js';
+import { runInstallDshHook, FLAGS as DSH_HOOK_FLAGS } from './install-dsh-hook.js';
+import { runInstallDshPreset, FLAGS as DSH_PRESET_FLAGS } from './install-dsh-preset.js';
+import { runInstallKimiPlugin, FLAGS as KIMI_PLUGIN_FLAGS } from './install-kimi-code-plugin.js';
+import { runInstallKimiHook, FLAGS as KIMI_HOOK_FLAGS } from './install-kimi-hook.js';
+import { runInstallOpenCodePlugin, FLAGS as OPENCODE_PLUGIN_FLAGS } from './install-opencode-plugin.js';
+import { runInstallQoderPlugin, FLAGS as QODER_PLUGIN_FLAGS } from './install-qoder-plugin.js';
+import { runInstallZCodePlugin, FLAGS as ZCODE_PLUGIN_FLAGS } from './install-zcode-plugin.js';
+
+
+// Which machine-level integrations a host has.
+// Deliberately not part of host-assets.json: that manifest
+// ships into user projects and declares asset facts, while
+// this is a property of the command surface. A gate keeps
+// the two in step.
+export const HOST_COMPONENTS = {
+  codex: {
+    default: 'plugin',
+    components: {
+      plugin: { summary: 'Codex plugin: marketplace source plus the bootstrap skill', flags: CODEX_PLUGIN_FLAGS, run: runInstallCodexPlugin }
+    }
+  },
+  'claude-code': {
+    default: 'plugin',
+    components: {
+      plugin: { summary: 'Claude Code skills-directory plugin: the bootstrap skill', flags: CLAUDE_CODE_PLUGIN_FLAGS, run: runInstallClaudeCodePlugin }
+    }
+  },
+  opencode: {
+    default: 'plugin',
+    components: {
+      plugin: { summary: 'OpenCode plugin: the plugin file plus the bootstrap skill it registers', flags: OPENCODE_PLUGIN_FLAGS, run: runInstallOpenCodePlugin }
+    }
+  },
+  zcode: {
+    default: 'plugin',
+    components: {
+      plugin: { summary: 'ZCode plugin: hooks, agents and the bootstrap skill', flags: ZCODE_PLUGIN_FLAGS, run: runInstallZCodePlugin }
+    }
+  },
+  qoder: {
+    default: 'plugin',
+    components: {
+      plugin: { summary: 'Qoder plugin: payload, registry entry and enable flag', flags: QODER_PLUGIN_FLAGS, run: runInstallQoderPlugin }
+    }
+  },
+  dsh: {
+    default: 'preset',
+    components: {
+      preset: { summary: 'DSH agent preset (bundles the hook, the primary path)', flags: DSH_PRESET_FLAGS, run: runInstallDshPreset },
+      hook: { summary: 'DSH workflow-state hook as a machine-level patch row', flags: DSH_HOOK_FLAGS, run: runInstallDshHook }
+    }
+  },
+  'kimi-code': {
+    default: 'plugin',
+    components: {
+      plugin: { summary: 'Kimi Code plugin: the bootstrap Skill it loads at session start', flags: KIMI_PLUGIN_FLAGS, run: runInstallKimiPlugin },
+      hook: { summary: 'Kimi Code context-injection hook (fallback when no plugin is installed)', flags: KIMI_HOOK_FLAGS, run: runInstallKimiHook }
+    }
+  }
+};
+
+
+// Every flag any installer accepts, in a stable order.
+// `host add` forwards argv unchanged, so installers stay
+// the only validators; this list is what `host add --help`
+// can name.
+export const HOST_FLAGS = [...new Set(
+  Object.values(HOST_COMPONENTS).flatMap(
+    (host) => Object.values(host.components).flatMap((component) => component.flags)
+  )
+)].sort();
+
+
+function resolveHost(token) {
+  const id = hostRegistry.platformIdFor(token);
+  if (id === null) {
+    throw new UsageError(
+      `Unknown host: ${token}. Declared hosts: ${hostRegistry.platformIds.join(', ')}`
+    );
+  }
+  const host = HOST_COMPONENTS[id];
+  return { id, host };
+}
+
+
+function resolveComponent(id, host, name) {
+  const componentName = name ?? host.default;
+  const component = host.components[componentName];
+  if (!component) {
+    throw new UsageError(
+      `Host ${id} has no component ${componentName}. `
+      + `Components: ${Object.keys(host.components).join(', ')}`
+    );
+  }
+  return component;
+}
+
+
+// `--component` is the only flag these two commands own;
+// everything else belongs to the installer and is
+// forwarded verbatim, so a flag this module never heard of
+// still reaches it and is validated there.
+function splitHostArgs(args) {
+  const { value: componentName, rest } = extractValueFlag(args, '--component');
+  const [token, ...forwarded] = rest;
+  if (token === undefined) {
+    throw new UsageError('Missing required argument: <host>');
+  }
+  const { id, host } = resolveHost(token);
+  return { id, component: resolveComponent(id, host, componentName), forwarded };
+}
+
+
+export async function runHostAdd(args = []) {
+  const { component, forwarded } = splitHostArgs(args);
+  return await component.run(forwarded);
+}
+
+
+export async function runHostRemove(args = []) {
+  const { component, forwarded } = splitHostArgs(args);
+  return await component.run(['--uninstall', ...forwarded]);
+}
+
+
+export async function runHostList(args = [], { io } = {}) {
+  const { flags, positionals } = parseFlags(args, {
+    boolean: ['--json'],
+    positional: { max: 1, name: '[target]' }
+  });
+  const target = resolve(positionals[0] ?? process.cwd());
+
+  const rows = [];
+  for (const platform of hostRegistry.platforms) {
+    // Every declared host has components;
+    // cli-registry.test.js asserts it.
+    const host = HOST_COMPONENTS[platform.id];
+    rows.push({
+      id: platform.id,
+      displayName: platform.displayName,
+      aliases: [...platform.aliases],
+      components: Object.keys(host.components),
+      defaultComponent: host.default,
+      // The per-project adapter record is the selection
+      // signal.
+      selected: await pathExists(join(target, ...platform.adapterPath.split('/')))
+    });
+  }
+
+  if (flags['--json']) {
+    io.writeOut(`${JSON.stringify({ target, hosts: rows }, null, 2)}\n`);
+    return 0;
+  }
+
+  const header = ['host', 'name', 'components', 'selected'];
+  const table = rows.map((row) => [
+    row.id,
+    row.displayName,
+    row.components.join(', '),
+    row.selected ? 'yes' : 'no'
+  ]);
+  const widths = header.map((cell, index) => Math.max(
+    cell.length,
+    ...table.map((line) => line[index].length)
+  ));
+  const format = (line) => line.map((cell, index) => cell.padEnd(widths[index])).join('  ').trimEnd();
+
+  io.writeOut(`Hosts declared in host-assets.json (project: ${target})\n`);
+  io.writeOut(`${format(header)}\n`);
+  for (const line of table) {
+    io.writeOut(`${format(line)}\n`);
+  }
+  io.writeOut('`selected` means this project has the host\'s adapter.\n');
+  return 0;
+}

package/src/commands/init.js

@@ -13,48 +13,33 @@ import {
   parsePlatformSelection,
   platformLabel
 } from '../lib/platforms.js';
+import { parseFlags, UsageError } from '../lib/cli-flags.js';
+
+// The manifest layer reports a plain Error; re-thrown as a
+// usage error so a bad host name exits with the
+// argv-mistake code.
+function parsePlatformSelectionOrUsage(values) {
+  try {
+    return parsePlatformSelection(values);
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+  }
+}
 
 function parseInitArgs(args) {
-  const options = {
-    developer: null,
-    dryRun: false,
-    force: false,
-    platforms: [],
-    target: process.cwd()
+  const { flags, positionals } = parseFlags(args, {
+    boolean: ['--dry-run', '--force'],
+    value: ['--platform', '--platforms', '--developer'],
+    repeatable: ['--platform', '--platforms'],
+    positional: { min: 0, max: 1, name: '[target]' }
+  });
+  return {
+    developer: flags['--developer'] ?? null,
+    dryRun: Boolean(flags['--dry-run']),
+    force: Boolean(flags['--force']),
+    platforms: [...(flags['--platform'] ?? []), ...(flags['--platforms'] ?? [])],
+    target: positionals[0] === undefined ? process.cwd() : resolve(positionals[0])
   };
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === '--dry-run') {
-      options.dryRun = true;
-    } else if (arg === '--force') {
-      options.force = true;
-    } else if (arg === '--platform' || arg === '--platforms') {
-      const value = args[index + 1];
-      if (!value || value.startsWith('--')) {
-        throw new Error('Missing value for --platform');
-      }
-      options.platforms.push(value);
-      index += 1;
-    } else if (arg.startsWith('--platform=')) {
-      options.platforms.push(arg.slice('--platform='.length));
-    } else if (arg.startsWith('--platforms=')) {
-      options.platforms.push(arg.slice('--platforms='.length));
-    } else if (arg === '--developer') {
-      const value = args[index + 1];
-      if (!value || value.startsWith('--')) {
-        throw new Error('Missing value for --developer');
-      }
-      options.developer = value;
-      index += 1;
-    } else if (arg.startsWith('--developer=')) {
-      options.developer = arg.slice('--developer='.length);
-    } else if (arg.startsWith('--')) {
-      throw new Error(`Unknown init option: ${arg}`);
-    } else {
-      options.target = resolve(arg);
-    }
-  }
-  return options;
 }
 
 async function pathExists(path) {
@@ -72,10 +57,10 @@ async function pathExists(path) {
 function normalizeDeveloperName(value) {
   const name = String(value ?? '').trim();
   if (!name) {
-    throw new Error('Developer name required. Run: cowork-flow init <target> --developer <name>');
+    throw new UsageError('Developer name required. Run: cwf project init <target> --developer <name>');
   }
   if (/[\\/]/.test(name)) {
-    throw new Error('Developer name must not contain path separators');
+    throw new UsageError('Developer name must not contain path separators');
   }
   return name;
 }
@@ -110,7 +95,7 @@ async function resolveDeveloperName(options, prompt) {
 
 async function resolvePlatforms(options, selectPlatforms) {
   if (options.platforms.length > 0) {
-    return parsePlatformSelection(options.platforms);
+    return parsePlatformSelectionOrUsage(options.platforms);
   }
 
   let selected = null;
@@ -124,7 +109,7 @@ async function resolvePlatforms(options, selectPlatforms) {
       defaultSelected: ['codex']
     });
   }
-  return parsePlatformSelection(selected);
+  return parsePlatformSelectionOrUsage(selected);
 }