Skip to content

Development

Prerequisites

  • Node.js 18+
  • npm 9+

Setup

git clone git@github.com:subscribed-aps/tools-package-subscribed-cli.git
cd tools-package-subscribed-cli
npm install
npm run compose   # builds and links the `subscribed` binary globally

After npm run compose, the subscribed command is available in your terminal and reflects the current build. Re-run it after making changes.

Project structure

src/
  bin/
    subscribed.ts       # binary entry point (just imports index.ts)
  commands/
    auth.ts             # auth login/logout/status
    deploy.ts           # deploy command
    log-sniff.ts        # log-sniff implementation
    logs.ts             # logs subcommand group (wraps log-sniff)
    workflow.ts         # workflow run command
  lib/
    config.ts           # config dir + auth token storage (~/.config/subscribed-cli)
    github.ts           # Octokit client, branch/workflow fetching, workflow dispatch
    projects.ts         # project registry (sites and packages)
  index.ts              # commander setup and command registration
dist/                   # compiled output (do not edit)
docs/                   # this documentation

Build

npm run build    # tsc → dist/
npm run dev      # build + run dist/index.js directly (no global link needed)

TypeScript is compiled with NodeNext module resolution. All local imports must use .js extensions (e.g. import { foo } from './lib/config.js'), even though the source files are .ts. This is a requirement of Node.js ESM.

Adding a command

  1. Create src/commands/your-command.ts and export a registerYourCommand(program: Command): void function.
  2. Import and call it in src/index.ts.
  3. Add a docs page at docs/commands/your-command.md.
  4. Update the commands table in README.md.

Adding a project

Open src/lib/projects.ts and add an entry to the PROJECTS array:

{
  key: 'my-project',          // used as CLI argument: subscribed deploy my-project
  name: 'My Project',         // display name in prompts
  repo: 'subscribed-aps/my-project-repo',
  type: 'site',               // 'site' | 'package'
  deployWorkflow: 'deploy.yml',
  environments: ['develop', 'production'],
  productionEnvironment: 'production', // optional — defaults to 'production'
                                       // set if your workflow uses a different name
}

No other files need to change.

Branching

Never commit directly to main. Always create a feature branch and open a PR:

git checkout -b feature/your-feature
# ... make changes ...
git push -u origin feature/your-feature
gh pr create