feat(ux): improve CLI usability across add, remove, compile, and list (#54)

* feat(ux): improve CLI usability across add, remove, compile, and list

- add: parallelize fetchRegistry with Promise.all (faster --list)
- add --list: show available assets (commands/templates/hooks/presets)
- add interactive: offer rules vs assets at startup
- add/remove: block format error now suggests category/name equivalent
- remove interactive: shows rules and assets together with separators
- compile --verbose: shows asset deployment separately from bridge files
- list assets: show output path for each installed asset
- assets: warn when template falls back to default output path
- docs: update remove.mdx to document asset removal

* test: add coverage for UX improvements (add, remove, assets, e2e)

- add.test.ts: tests for updateConfigAssets (preserve, replace, multi-type)
- remove.test.ts: tests for mixed pulled+assets config state
- assets.test.ts: tests for deployTemplates fallback and custom output_path
- e2e/cli.test.ts: tests for block format hint in add/remove error messages

Author: gpolanco

.gitignore

@@ -43,6 +43,5 @@ coverage/
 # Misc
 *.tgz
 .dwf/.cache/
-docs/internal
 openspec/
 .vercel

docs/commands/remove.mdx

@@ -1,34 +1,48 @@
 ---
 title: "devw remove"
-description: "Remove an installed rule"
+description: "Remove an installed rule or asset"
 ---
 
 ```bash
-devw remove [category/rule]
+devw remove [category/name]
 ```
 
-Removes a rule that was installed via `devw add` and recompiles.
+Removes a rule or asset that was installed via `devw add` and recompiles.
 
 ## Interactive Mode
 
 Running `devw remove` without arguments shows installed rules and lets you select which to remove.
 
+> Note: interactive mode only lists rules. To remove an asset, use the direct form.
+
 ## Direct Mode
 
 ```bash
+# Remove a rule
 devw remove typescript/strict
+
+# Remove an asset
+devw remove command/spec
+devw remove template/feature-spec
+devw remove hook/auto-format
 ```
 
-Removes the rule file (`pulled-typescript-strict.yml`) and updates `config.yml`.
+Removes the file from `.dwf/rules/` or `.dwf/assets/<type>s/` and updates `config.yml`. Recompiles automatically.
 
 ## Examples
 
 ```bash
+# Interactive — select rules to remove
+devw remove
+
 # Remove a specific rule
 devw remove typescript/strict
 
-# Interactive — select rules to remove
-devw remove
+# Remove a slash command
+devw remove command/spec
+
+# Remove an editor hook
+devw remove hook/auto-format
 ```
 
 Rules added manually (not via `devw add`) are not affected.

packages/cli/src/commands/add.ts

@@ -4,7 +4,7 @@ import type { Command } from 'commander';
 import chalk from 'chalk';
 import { stringify, parse } from 'yaml';
 import { select, checkbox, confirm } from '@inquirer/prompts';
-import { fetchRawContent, fetchContent, listDirectory } from '../utils/github.js';
+import { fetchRawContent, fetchContent, listDirectory, listContentDirectory } from '../utils/github.js';
 import { convert } from '../core/converter.js';
 import { isAssetType, parseAssetFrontmatter } from '../core/assets.js';
 import { fileExists } from '../utils/fs.js';
@@ -65,38 +65,39 @@ export async function fetchRegistry(cwd: string): Promise<CachedRegistry | null>
     return null;
   }
 
-  const categories: CachedRegistry['categories'] = [];
+  const dirs = topLevel.filter((e) => e.type === 'dir');
 
-  for (const entry of topLevel) {
-    if (entry.type !== 'dir') continue;
-
-    try {
-      const files = await listDirectory(entry.name);
-      const rules: Array<{ name: string; description: string }> = [];
-
-      for (const file of files) {
-        if (file.type !== 'file') continue;
-        try {
-          const content = await fetchRawContent(`${entry.name}/${file.name}`);
-          const fmMatch = /^---\n([\s\S]*?)\n---/.exec(content);
-          if (fmMatch?.[1]) {
-            const fm = parse(fmMatch[1]) as Record<string, unknown>;
-            const description = typeof fm['description'] === 'string' ? fm['description'] : '';
-            rules.push({ name: file.name, description });
-          }
-        } catch {
-          rules.push({ name: file.name, description: '' });
-        }
-      }
+  const categoryResults = await Promise.all(
+    dirs.map(async (entry) => {
+      try {
+        const files = await listDirectory(entry.name);
+        const ruleFiles = files.filter((f) => f.type === 'file');
+
+        const rules = await Promise.all(
+          ruleFiles.map(async (file) => {
+            try {
+              const content = await fetchRawContent(`${entry.name}/${file.name}`);
+              const fmMatch = /^---\n([\s\S]*?)\n---/.exec(content);
+              if (fmMatch?.[1]) {
+                const fm = parse(fmMatch[1]) as Record<string, unknown>;
+                const description = typeof fm['description'] === 'string' ? fm['description'] : '';
+                return { name: file.name, description };
+              }
+              return { name: file.name, description: '' };
+            } catch {
+              return { name: file.name, description: '' };
+            }
+          }),
+        );
 
-      if (rules.length > 0) {
-        categories.push({ name: entry.name, rules });
+        return rules.length > 0 ? { name: entry.name, rules } : null;
+      } catch {
+        return null;
       }
-    } catch {
-      // Skip categories that fail to list
-    }
-  }
+    }),
+  );
 
+  const categories = categoryResults.filter((c): c is NonNullable<typeof c> => c !== null);
   const registry: CachedRegistry = { categories };
   await cache.set(cwd, 'registry', registry);
   return registry;
@@ -137,6 +138,38 @@ async function runList(categoryFilter: string | undefined): Promise<void> {
   }
 
   console.log(`  ${chalk.dim(`Add a rule:  devw add <category>/<rule>`)}`);
+
+  // Show available assets if not filtering by category
+  if (!categoryFilter) {
+    const assetTypes = ['commands', 'templates', 'hooks', 'presets'] as const;
+    const assetResults = await Promise.allSettled(
+      assetTypes.map((dir) => listContentDirectory(dir)),
+    );
+
+    const hasAnyAssets = assetResults.some(
+      (r) => r.status === 'fulfilled' && r.value.some((e) => e.type === 'file'),
+    );
+
+    if (hasAnyAssets) {
+      ui.newline();
+      ui.header('Available assets');
+      ui.newline();
+      for (let i = 0; i < assetTypes.length; i++) {
+        const type = assetTypes[i]!;
+        const result = assetResults[i]!;
+        if (result.status !== 'fulfilled') continue;
+        const names = result.value.filter((e) => e.type === 'file').map((e) => e.name);
+        if (names.length === 0) continue;
+        const singular = type.replace(/s$/, '');
+        console.log(`  ${chalk.cyan(`${singular}/`)}`);
+        for (const name of names) {
+          console.log(`    ${chalk.white(name)}`);
+        }
+        ui.newline();
+      }
+      console.log(`  ${chalk.dim(`Add an asset: devw add command/<name>`)}`);
+    }
+  }
 }
 
 export function generateYamlOutput(
@@ -388,7 +421,94 @@ async function downloadAndInstall(
   return true;
 }
 
+async function runInteractiveAsset(cwd: string, options: AddOptions): Promise<void> {
+  let assetType: AssetType | 'preset';
+  try {
+    assetType = await select<AssetType | 'preset'>({
+      message: 'Asset type',
+      choices: [
+        { name: 'command  — Slash commands for Claude Code', value: 'command' },
+        { name: 'template — Spec and document templates', value: 'template' },
+        { name: 'hook     — Editor hooks (auto-format, etc.)', value: 'hook' },
+        { name: 'preset   — Bundle of rules + assets', value: 'preset' },
+      ],
+    });
+  } catch {
+    ui.error('Cancelled');
+    return;
+  }
+
+  ui.info(`Fetching available ${assetType}s from GitHub...`);
+
+  let names: string[];
+  try {
+    const entries = await listContentDirectory(`${assetType}s`);
+    names = entries.filter((e) => e.type === 'file').map((e) => e.name);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ui.error(`Could not fetch ${assetType} list: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (names.length === 0) {
+    ui.warn(`No ${assetType}s available in registry`);
+    return;
+  }
+
+  let selected: string[];
+  try {
+    selected = await checkbox<string>({
+      message: `Select ${assetType}s to install`,
+      choices: names.map((name) => ({ name, value: name })),
+    });
+  } catch {
+    ui.error('Cancelled');
+    return;
+  }
+
+  if (selected.length === 0) {
+    ui.warn('No assets selected');
+    return;
+  }
+
+  let anyAdded = false;
+  for (const name of selected) {
+    if (assetType === 'preset') {
+      const added = await installPreset(cwd, name, options);
+      if (added) anyAdded = true;
+    } else {
+      const added = await downloadAndInstallAsset(cwd, assetType, name, options);
+      if (added) anyAdded = true;
+    }
+  }
+
+  if (anyAdded && !options.noCompile) {
+    const { runCompileFromAdd } = await import('./compile.js');
+    await runCompileFromAdd();
+  }
+}
+
 async function runInteractive(cwd: string, options: AddOptions): Promise<void> {
+  let mode: 'rules' | 'assets';
+  try {
+    mode = await select<'rules' | 'assets'>({
+      message: 'What do you want to add?',
+      choices: [
+        { name: 'Rules    — Install rules from the registry', value: 'rules' },
+        { name: 'Assets   — Commands, templates, hooks, presets', value: 'assets' },
+      ],
+    });
+  } catch {
+    ui.error('Cancelled');
+    return;
+  }
+
+  if (mode === 'assets') {
+    await runInteractiveAsset(cwd, options);
+    return;
+  }
+
   const registry = await fetchRegistry(cwd);
   if (!registry) {
     process.exitCode = 1;
@@ -623,7 +743,15 @@ async function runAdd(ruleArg: string | undefined, options: AddOptions): Promise
   }
 
   if (!ruleArg.includes('/')) {
-    ui.error('Block format is no longer supported', 'Use: devw add <category>/<rule>. Run devw add --list to browse.');
+    const dashIdx = ruleArg.indexOf('-');
+    const hint =
+      dashIdx > 0
+        ? `devw add ${ruleArg.slice(0, dashIdx)}/${ruleArg.slice(dashIdx + 1)}`
+        : `devw add <category>/<rule>`;
+    ui.error(
+      `Block format "${ruleArg}" is no longer supported`,
+      `Use category/name format — e.g., ${hint}. Run devw add --list to browse.`,
+    );
     process.exitCode = 1;
     return;
   }

packages/cli/src/commands/compile.ts

@@ -193,7 +193,15 @@ async function runCompile(options: CompileOptions): Promise<void> {
     ui.newline();
     ui.success(`Compiled ${String(result.activeRuleCount)} rules ${ICONS.arrow} ${String(allPaths.length)} file${allPaths.length !== 1 ? 's' : ''} ${ui.timing(result.elapsedMs)}`);
     ui.newline();
-    ui.list(allPaths);
+
+    if (options.verbose && result.assetPaths.length > 0) {
+      ui.list(writtenPaths);
+      ui.newline();
+      console.log(`  ${chalk.dim('Assets deployed:')}`);
+      ui.list(result.assetPaths);
+    } else {
+      ui.list(allPaths);
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     ui.error(message);

packages/cli/src/commands/list.ts

@@ -89,6 +89,19 @@ async function listTools(): Promise<void> {
   }
 }
 
+function getAssetOutputHint(type: string, name: string): string {
+  switch (type) {
+    case ASSET_TYPE.Command:
+      return `.claude/commands/${name}.md`;
+    case ASSET_TYPE.Template:
+      return `docs/specs/${name}.md`;
+    case ASSET_TYPE.Hook:
+      return `.claude/settings.local.json`;
+    default:
+      return '';
+  }
+}
+
 async function listAssets(typeFilter?: string): Promise<void> {
   const cwd = process.cwd();
   if (!(await ensureConfig(cwd))) return;
@@ -110,7 +123,8 @@ async function listAssets(typeFilter?: string): Promise<void> {
   ui.header(`Installed ${label} (${String(filtered.length)})`);
   ui.newline();
   for (const asset of filtered) {
-    console.log(`    ${chalk.dim(ICONS.bullet)} ${chalk.cyan(asset.type.padEnd(10))} ${chalk.white(asset.name.padEnd(20))} ${chalk.dim(`v${asset.version}`)}`);
+    const outputHint = getAssetOutputHint(asset.type, asset.name);
+    console.log(`    ${chalk.dim(ICONS.bullet)} ${chalk.cyan(asset.type.padEnd(10))} ${chalk.white(asset.name.padEnd(20))} ${chalk.dim(`v${asset.version}`)}  ${chalk.dim(ICONS.arrow)} ${chalk.dim(outputHint)}`);
   }
 }