Add module mode aliases and class groups

[mmkal]

Summary

Adds the next scoped module-mode features:

• JSDoc @alias tags on exported functions become command aliases.
• JSDoc @alias tags on option properties become option aliases.
• Alias tags are stripped from help descriptions.
• Exported functions whose signatures cannot be converted into CLI inputs are ignored as ordinary non-command exports; NoInfer<...> parameters are a convenient opt-out for helper exports.
• Direct command-group-shaped exported classes become same-file subcommand groups.
• export default class Commands { ... } exposes public methods at the current router level.
• Class groups are constrained to constructor-free instantiation: classes without a base class may omit the constructor, and classes with extends must declare an explicit zero-argument constructor.
• Unsupported class shapes, including constructor parameters, unsupported inheritance, and classes with no public command methods, are ignored as ordinary non-command exports.
• Public instance methods become commands; static methods, inherited methods, getters/setters, private/protected methods, and #private methods stay internal.
• Class instances are created lazily inside command handlers, so help/schema generation does not run constructors.
• File-backed module mode supports selected named re-exports like export {Users} from './users.ts'.
• File-backed module mode resolves relative imported type/interface declarations, including common .js specifiers that point at sibling .ts source files.
• Documents the current same-file type support boundary, including extended interfaces and object intersections.

Also widens .run({prompts}) so prompts: false and computed booleans like prompts: !isAgent() are valid; true still enables built-in prompts and false disables prompting.

Exported norpc procedure/router support remains out of scope for a separate change.

Examples

/**
 * install dependencies
 * @alias i
 */
export function install(options: {
  /** fail if the lockfile changed
   * @alias f
   */
  frozenLockfile?: boolean
}) {
  return options.frozenLockfile ? 'frozen' : 'normal'
}

export const loadSomeInternalThing = (params: NoInfer<{foo: string}>) => {
  return loadIt(params.foo) // helper export, not a command
}

class BaseUsers {
  protected prefix = 'invite'
}

export class Users extends BaseUsers {
  constructor() {
    super()
  }

  /** invite a user
   * @alias i
   */
  invite(options: {
    /** address to invite */
    email: string
  }) {
    const user = this.getOrCreate(options.email)
    return `${this.prefix} ${user.email}`
  }

  private getOrCreate(email: string) {
    return {email}
  }

  #audit(action: string) {
    // private implementation detail, not a command
  }
}

// commands.ts
import type {InviteOptions} from './types.js'

export {Users} from './users.ts'

export default class Commands {
  invite(options: InviteOptions) {
    return `invite ${options.email}`
  }
}

$ mycli i -f
frozen

$ tsx commands.ts invite --email [email protected]
invite [email protected]

$ tsx commands.ts users invite --email [email protected]
invite [email protected]

$ mycli users i --email [email protected]
invite [email protected]

await cli.run({
  prompts: !isAgent(),
})

Verification

• pnpm exec vitest run test/typebox-module-commands.test.ts
• pnpm exec vitest run test/prompts.test.ts test/types.test.ts
• pnpm exec eslint README.md src/module-commands.ts src/types.ts test/typebox-module-commands.test.ts
• pnpm exec eslint README.md src/types.ts test/prompts.test.ts test/types.test.ts
• pnpm compile
• pnpm test
• pnpm lint

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/mmkal/trpc-cli@211

commit: 13f3909

[pullfrog]

✅ No new issues found.

Reviewed changes — Adds JSDoc @alias tag support and exported class command groups to module mode, along with documentation of the same-file type support boundary.

• Add @alias JSDoc tag support for commands and options — @alias tags on exported functions produce meta.aliases.command, and on option properties produce schema-level alias fields, fed through the existing Commander aliasing pipeline. Tags are stripped from help descriptions so only prose renders.
• Add exported class command groups — export class Group { method() {} } creates a lazy-instantiated subcommand group. No extends, no constructor args, public instance methods only. The class is NOT instantiated during help/schema generation; a fresh instance is created per-command invocation.
• Document same-file type support boundary — Interface extends, multiple bases, and object intersections are documented as supported; imported types remain out of scope and fail loudly.
• New extraction primitives — extractModuleClasses, extractClassMethods, parseCliJsdoc, applySchemaJsdocMetadata follow the same hand-rolled scanSource/masked pattern as the existing function extractor.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[github-actions]

This is included in v0.15.1.