@tanstack/cli 0.61.1 → 0.62.1

package/skills/maintain-custom-addons-dev-watch/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: maintain-custom-addons-dev-watch
+description: >
+  Build and iterate custom add-ons/templates with tanstack add-on init,
+  add-on compile, add-on dev, and tanstack dev --dev-watch, including sync
+  loop preconditions, watch-path validation, and project metadata constraints.
+type: lifecycle
+library: tanstack-cli
+library_version: "0.61.0"
+requires:
+  - add-addons-existing-app
+---
+
+# Maintain Custom Add-ons In Dev Watch
+
+Use this skill for local add-on authoring workflows where you continuously compile and sync package output into a target app.
+
+## Setup
+
+```bash
+npx @tanstack/cli add-on init
+npx @tanstack/cli add-on compile
+```
+
+## Core Patterns
+
+### Run add-on dev loop while editing source
+
+```bash
+npx @tanstack/cli add-on dev
+```
+
+### Sync watched package output into target app
+
+```bash
+npx @tanstack/cli dev --dev-watch ../my-addon-package
+```
+
+### Re-run compile before apply when changing metadata
+
+```bash
+npx @tanstack/cli add-on compile
+npx @tanstack/cli add my-custom-addon
+```
+
+## Common Mistakes
+
+### HIGH Use --dev-watch with --no-install
+
+Wrong:
+```bash
+npx @tanstack/cli dev --dev-watch ../my-addon-package --no-install
+```
+
+Correct:
+```bash
+npx @tanstack/cli dev --dev-watch ../my-addon-package
+```
+
+Dev-watch rejects `--no-install`, so automated loops fail before any sync work starts.
+
+Source: packages/cli/src/dev-watch.ts:112
+
+### HIGH Start dev-watch without valid package entry
+
+Wrong:
+```bash
+npx @tanstack/cli dev --dev-watch ../missing-or-invalid-package
+```
+
+Correct:
+```bash
+npx @tanstack/cli dev --dev-watch ../valid-addon-package
+```
+
+Watch setup validates path and package metadata first, so invalid targets fail before file syncing begins.
+
+Source: packages/cli/src/dev-watch.ts:100
+
+### CRITICAL Author add-on from code-router project
+
+Wrong:
+```bash
+npx @tanstack/cli add-on init
+```
+
+Correct:
+```bash
+# Run add-on init from a file-router project
+npx @tanstack/cli add-on init
+```
+
+Custom add-on authoring expects file-router mode and exits when run from incompatible project modes.
+
+Source: packages/create/src/custom-add-ons/add-on.ts
+
+### HIGH Run add-on workflows without scaffold metadata
+
+Wrong:
+```bash
+npx @tanstack/cli add-on dev
+```
+
+Correct:
+```bash
+# Run in a project scaffolded by TanStack CLI (contains .cta.json), then:
+npx @tanstack/cli add-on dev
+```
+
+Custom add-on flows rely on persisted scaffold options, so missing metadata blocks initialization and update paths.
+
+Source: packages/create/src/custom-add-ons/shared.ts:158
+
+### HIGH Tension: Backwards support vs deterministic automation
+
+This domain's patterns conflict with add-addons-existing-app. Tooling assumes reusable automation, but hidden metadata preconditions from legacy support make add-on loops non-portable across repositories.
+
+See also: add-addons-existing-app/SKILL.md § Common Mistakes

package/skills/query-docs-library-metadata/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: query-docs-library-metadata
+description: >
+  Retrieve machine-readable context with tanstack libraries, tanstack doc,
+  tanstack search-docs, tanstack create --list-add-ons --json, and
+  --addon-details for agent-safe discovery and preflight validation.
+type: core
+library: tanstack-cli
+library_version: "0.61.0"
+---
+
+# Query Docs And Library Metadata
+
+Use this skill to collect authoritative context before code generation or integration selection.
+
+## Setup
+
+```bash
+npx @tanstack/cli libraries --json
+```
+
+## Core Patterns
+
+### Resolve valid library ids before doc fetch
+
+```bash
+npx @tanstack/cli libraries --json
+```
+
+### Fetch a specific docs page with explicit version
+
+```bash
+npx @tanstack/cli doc --library router --version latest --path /docs/framework/react/guide/routing
+```
+
+### Search docs for implementation targets
+
+```bash
+npx @tanstack/cli search-docs "server functions" --library start --json
+```
+
+## Common Mistakes
+
+### HIGH Use invalid library id/version/path for doc fetch
+
+Wrong:
+```bash
+npx @tanstack/cli doc --library made-up-lib --version latest --path /docs
+```
+
+Correct:
+```bash
+npx @tanstack/cli libraries --json
+npx @tanstack/cli doc --library router --version latest --path /docs/framework/react/guide/routing
+```
+
+`doc` validates identifiers against registry metadata and fails when any segment is not real.
+
+Source: packages/cli/src/cli.ts:746
+
+### MEDIUM Rely on deprecated create alias for discovery
+
+Wrong:
+```bash
+npx create-tsrouter-app --list-add-ons
+```
+
+Correct:
+```bash
+npx @tanstack/cli create --list-add-ons --json
+```
+
+Legacy alias workflows can produce confusing outputs that do not match current CLI discovery behavior. Fixed in newer versions, but agents trained on older examples may still generate this pattern.
+
+Source: https://github.com/TanStack/cli/issues/93
+
+### HIGH Tension: Single-command convenience vs integration precision
+
+This domain's patterns conflict with create-app-scaffold and choose-ecosystem-integrations. Skipping discovery to run one-shot scaffold commands tends to lock in plausible defaults that miss architecture constraints.
+
+See also: create-app-scaffold/SKILL.md § Common Mistakes
+
+## References
+
+- [Discovery command output schemas](references/discovery-command-output-schemas.md)

package/skills/query-docs-library-metadata/references/discovery-command-output-schemas.md

@@ -0,0 +1,70 @@
+# Discovery Command Output Schemas
+
+Targets `@tanstack/cli` v0.61.0.
+
+## `tanstack libraries --json`
+
+```json
+{
+  "count": 3,
+  "libraries": [
+    {
+      "id": "router",
+      "label": "TanStack Router",
+      "description": "Type-safe routing",
+      "latestVersion": "latest"
+    }
+  ]
+}
+```
+
+## `tanstack search-docs <query> --json`
+
+```json
+{
+  "query": "server functions",
+  "results": [
+    {
+      "library": "start",
+      "version": "latest",
+      "title": "Server Functions",
+      "path": "/docs/framework/react/guide/server-functions"
+    }
+  ]
+}
+```
+
+## `tanstack create --list-add-ons --json`
+
+```json
+{
+  "count": 4,
+  "addOns": [
+    {
+      "id": "drizzle",
+      "name": "Drizzle",
+      "category": "database",
+      "dependsOn": []
+    }
+  ]
+}
+```
+
+## `tanstack create --addon-details <id> --json`
+
+```json
+{
+  "id": "prisma",
+  "name": "Prisma",
+  "options": [
+    {
+      "name": "provider",
+      "default": "postgres",
+      "choices": ["postgres", "sqlite", "mysql"]
+    }
+  ],
+  "dependsOn": []
+}
+```
+
+Use this reference to parse shapes defensively and normalize fields before feeding downstream planning or generation steps.