refactor: migrate CLI to cac and fix monorepo workflow generation (#85)

* feat: refactor CLI to use cac for command handling and improve command structure

* feat: refactor CLI commands and improve error handling structure

* feat: implement validation command for skill files and refactor CLI structure

* feat: add runStaleCommand for handling stale targets in CLI

* feat: implement runMetaCommand for managing meta-skills in CLI

* feat: add commands for editing package.json and setting up GitHub actions in CLI

* feat: enhance CLI help command structure and usage examples

* feat: enhance setup for monorepos with workspace detection and workflow generation

* feat: refactor CLI structure by moving utility functions to cli-support module

* refactor: change readPackageName function to private scope in cli-support module

* changeset

* test: update `cac`

* Apply code review and simplification fixes

- Brand CliFailure with symbol to prevent duck-typing false positives
- Handle CACError in catch block for clean CLI error output
- Fix unsafe (err as Error).message cast in scanIntentsOrFail
- Include YAML parse error details in validation messages
- Add monorepo artifact rationale comment in validate.ts
- Fix misleading src path comment in setup.ts
- Complete template variable list in docs
- Add comment explaining cac double-argument quirk
- Extract shared printWarnings to cli-support module
- Move ValidationError interface to module scope
- Extract isInsideMonorepo helper from IIFE

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

* Downgrade cac to keep older Node support

---------

Co-authored-by: Kyle Mathews <mathews.kyle@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 4 people

.changeset/thin-rings-behave.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/intent': patch
+---
+
+Refactored the CLI to use `cac`, replacing the previous hand-rolled parsing and dispatch logic with a more structured command system.
+
+This update also fixes monorepo workflow generation behavior related to `setup-github-actions`, improving repo/package fallback handling and ensuring generated workflow watch paths are monorepo-aware.

docs/cli/intent-setup.md

@@ -24,7 +24,9 @@ npx @tanstack/intent@latest setup-github-actions
   - Preserves existing indentation
 - `setup-github-actions`
   - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
-  - Applies variable substitution for `PACKAGE_NAME`, `REPO`, `DOCS_PATH`, `SRC_PATH`
+  - Applies variable substitution (`PACKAGE_NAME`, `PACKAGE_LABEL`, `PAYLOAD_PACKAGE`, `REPO`, `DOCS_PATH`, `SRC_PATH`, `WATCH_PATHS`)
+  - Detects the workspace root in monorepos and writes repo-level workflows there
+  - Generates monorepo-aware watch paths for package `src/` and docs directories
   - Skips files that already exist at destination
 
 ## Required `files` entries
@@ -42,6 +44,7 @@ npx @tanstack/intent@latest setup-github-actions
 ## Notes
 
 - `setup-github-actions` skips existing files
+- In monorepos, run `setup-github-actions` from either the repo root or a package directory; Intent writes workflows to the workspace root
 
 ## Related
 

packages/intent/package.json

@@ -27,6 +27,7 @@
     "meta"
   ],
   "dependencies": {
+    "cac": "^6.7.14",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
@@ -37,6 +38,7 @@
   "scripts": {
     "prepack": "npm run build",
     "build": "tsdown src/index.ts src/cli.ts src/setup.ts src/intent-library.ts src/library-scanner.ts --format esm --dts",
+    "test:smoke": "pnpm run build && node dist/cli.mjs --help > /dev/null",
     "test:lib": "vitest run --exclude 'tests/integration/**'",
     "test:integration": "vitest run tests/integration/",
     "test:types": "tsc --noEmit"

packages/intent/src/cli-error.ts

@@ -0,0 +1,18 @@
+const CLI_FAILURE = Symbol('CliFailure')
+
+export type CliFailure = {
+  readonly [CLI_FAILURE]: true
+  message: string
+  exitCode: number
+}
+
+// Throws a structured CliFailure (not an Error) — this represents an expected
+// user-facing failure, not an internal bug. Stack traces are intentionally
+// omitted since these are anticipated exit paths (bad input, missing files, etc).
+export function fail(message: string, exitCode = 1): never {
+  throw { [CLI_FAILURE]: true as const, message, exitCode } satisfies CliFailure
+}
+
+export function isCliFailure(value: unknown): value is CliFailure {
+  return !!value && typeof value === 'object' && CLI_FAILURE in value
+}

packages/intent/src/cli-support.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { fail } from './cli-error.js'
+import type { ScanResult, StalenessReport } from './types.js'
+
+export function printWarnings(warnings: Array<string>): void {
+  if (warnings.length === 0) return
+
+  console.log('Warnings:')
+  for (const warning of warnings) {
+    console.log(`  ⚠ ${warning}`)
+  }
+}
+
+export function getMetaDir(): string {
+  const thisDir = dirname(fileURLToPath(import.meta.url))
+  return join(thisDir, '..', 'meta')
+}
+
+export async function scanIntentsOrFail(): Promise<ScanResult> {
+  const { scanForIntents } = await import('./scanner.js')
+
+  try {
+    return scanForIntents()
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err))
+  }
+}
+
+function readPackageName(root: string): string {
+  try {
+    const pkgJson = JSON.parse(
+      readFileSync(join(root, 'package.json'), 'utf8'),
+    ) as {
+      name?: unknown
+    }
+    return typeof pkgJson.name === 'string'
+      ? pkgJson.name
+      : relative(process.cwd(), root) || 'unknown'
+  } catch {
+    return relative(process.cwd(), root) || 'unknown'
+  }
+}
+
+export async function resolveStaleTargets(
+  targetDir?: string,
+): Promise<{ reports: Array<StalenessReport> }> {
+  const resolvedRoot = targetDir
+    ? join(process.cwd(), targetDir)
+    : process.cwd()
+  const { checkStaleness } = await import('./staleness.js')
+
+  if (existsSync(join(resolvedRoot, 'skills'))) {
+    return {
+      reports: [
+        await checkStaleness(resolvedRoot, readPackageName(resolvedRoot)),
+      ],
+    }
+  }
+
+  const { findPackagesWithSkills, findWorkspaceRoot } =
+    await import('./setup.js')
+  const workspaceRoot = findWorkspaceRoot(resolvedRoot)
+  if (workspaceRoot) {
+    const packageDirs = findPackagesWithSkills(workspaceRoot)
+    if (packageDirs.length > 0) {
+      return {
+        reports: await Promise.all(
+          packageDirs.map((packageDir) =>
+            checkStaleness(packageDir, readPackageName(packageDir)),
+          ),
+        ),
+      }
+    }
+  }
+
+  const staleResult = await scanIntentsOrFail()
+  return {
+    reports: await Promise.all(
+      staleResult.packages.map((pkg) =>
+        checkStaleness(pkg.packageRoot, pkg.name),
+      ),
+    ),
+  }
+}