CLI 1.33.0: mods from aitmpl.com, short names, --search, system-folder guard

Merged
DA
13d ago
+882-71

Requested by Daniel · project thread

What this PR does

Initiative 6 of the traction plan (CLI 1.33). Targets: mod-run failures 15.5% → <3%, total failures 2.4% → ≤1.5%.

  • Mods from aitmpl.com (cli-tool/src/component-content.js): one request to www.aitmpl.com/component-content/mods/{cat}/{name}.json, accepted only if its files equal meta.files (same paths, same byte sizes, no extra files, safe paths). Otherwise it falls back to the GitHub contents API, which now names its rate limit in the error. All 50 current mod content files pass the check (covered by a test). Skills still come from GitHub, as the spec says.
  • System-folder guard (target-guard.js): refuses %SystemRoot% (and anything under it) and drive roots (/ on POSIX), writes nothing, exits 1 and says which folder to open. A user-scope --plugin is exempt because it writes nothing in the cwd. The refusal is tracked as errorType: unsafe_directory, so it still counts as a failure in installation_outcomes.
  • Short names and "did you mean" (catalog-lookup.js, Catalog API v1 with the catalog browser's cache): a name resolves only when exactly one component of that type has it (--agent frontend-developer → development-team/frontend-developer). Ambiguous or missing names are still attempted as typed, because the catalog can lag main. When they fail, the summary prints Did you mean: commands or a --search command, never the same failing Retry. If the catalog is unreachable, names stay as typed.
  • --search "<words>": up to 5 results ranked by text match (never by downloads), each with a page (utm_medium=search) and an install command. It is tracked as the search command with the result count only, never the words.
  • After an install: Page: lines (utm_source=cli&utm_medium=install) and, for 2 or more components, a Stack: line with the combined command. The /s/ stack page (initiative 9) does not exist yet, so the command is the fallback the spec allows. The output is the same plain lines in TTY and non-TTY.
  • Help examples no longer print cct --agent. The cct binary itself is untouched until decision 16. The no-terminal help lists --plugin and --search.
  • usage-tracking.ts: search, check-updates and update added to VALID_COMMANDS.
  • Version synced to 1.33.0 (not published), plus the CHANGELOG, the docs-site flags page with its regenerated snippet, and the README.

Release order: the dashboard deploy that accepts search must be live before npm publish, or the search events get rejected (best effort, so nothing breaks).

Type

  • New component
  • Change to an existing component
  • CLI (cli-tool/src, cli-tool/bin)
  • Website (dashboard/)
  • Docs or other

How I tested it

  • npm test (root, now includes cli-install-fixes.node-test.js: 14 tests), dashboard usage-tracking.test.ts and the jest install-ui/catalog-browser suites: all green. check_docs.py OK.
  • From the npm pack tarball (1.33.0) installed into a scratch project, with CCT_NO_TRACKING=true:
    • --mod stack-viewer,games/cc-arcade --skill pdf --agent frontend-develper --yes: both mods came from aitmpl.com (6 and 34 files), stack-viewer and pdf resolved by short name, the typo printed Did you mean: … --agent development-team/frontend-developer, then the Page and Stack lines.
    • --search "secret redactor", --directory / (refused, exit 1) and the no-TTY help.
    • With CCT_CONTENT_URL pointing at a dead host, the GitHub fallback ran. The container's IP was rate-limited by GitHub, which reproduced the real-world failure with the new message. The skill install failed with a GitHub 403 for the same reason, which is unrelated to this PR.
  • Not tested on real Windows. The guard is unit-tested with path.win32.

Generated by Claude Code


Summary by cubic

CLI 1.33.0 ships install-reliability fixes: mods now download from aitmpl.com instead of the rate-limited GitHub contents API, short names resolve through the catalog, a new --search flag finds components, and the CLI refuses to install into system folders.

Notes

  • CLI (cli-tool/src, cli-tool/bin): mod downloads first try www.aitmpl.com/component-content/mods/{cat}/{name}.json, accepted only when files match meta.files (paths and byte sizes); GitHub is the fallback and now names its rate limit. Skills still come from GitHub.
  • New --search "<words>" prints up to 5 text matches with their page and install command; missing or ambiguous names print Did you mean: commands instead of repeating the failing install. A guard refuses C:\Windows (and below) and drive roots, writes nothing, and exits 1.
  • --mod and --search add no new .json sources, so the catalog (docs/components.json) needs no regeneration; only source modules (catalog-lookup.js, component-content.js, target-guard.js) and tests were added.
  • Website: the dashboard's usage-tracking.ts accepts the new search command (plus check-updates/update reserved for 1.34); docs-site flags page, README, and CHANGELOG updated.
  • No new secrets; optional CCT_CONTENT_URL env var (https, /component-content suffix only) overrides the content host for testing. The dashboard deploy that accepts search must be live before npm publish so search events are not rejected.