@classytic/dev-tools

Shared dev-workflow tooling for @classytic packages. Ships the classytic-bot authenticated push helper; future workflow helpers land as additional binaries in this same package.

Install

npm i -D @classytic/dev-tools

Node 22+ required. Zero runtime dependencies — the package uses only node:crypto and the built-in fetch.

classytic-push

Mint a short-lived classytic-bot installation token and push a branch attributed to the bot. Pairs cleanly with commits authored as classytic-bot[bot] so both the commit author AND the pusher show the bot identity in GitHub.

Usage

# current branch
npx classytic-push

# specific branch
npx classytic-push release/2.11

# extra git-push flags pass through
npx classytic-push main --tags

As an npm script:

{
  "scripts": {
    "push": "classytic-push"
  }
}

Config (env vars — set directly OR via a .env file)

| Variable | Required | Default | Purpose | |---|---|---|---| | CLASSYTIC_BOT_APP_ID | yes | — | GitHub App ID (public) | | CLASSYTIC_BOT_PEM | one of these two | — | Inline PEM contents (preferred in CI) | | CLASSYTIC_BOT_PEM_PATH | one of these two | — | Path to .pem on disk (preferred locally) | | CLASSYTIC_BOT_OWNER | no | classytic | Org login the App is installed on | | CLASSYTIC_BOT_ENV_FILE | no | — | Explicit path to a .env file to load | | CLASSYTIC_BOT_DEBUG | no | — | Set to anything truthy to log which .env file was loaded |

CLASSYTIC_BOT_PEM wins over CLASSYTIC_BOT_PEM_PATH when both are set.

.env auto-discovery (0.2.0+)

The CLI walks up from the current directory looking for .env.local then .env — the first file found wins. Put a single .env at the workspace root (e.g. D:/projects/classytic/.env) and every classytic repo nested underneath inherits the config:

# D:/projects/classytic/.env  — gitignored, synced across machines however you prefer
CLASSYTIC_BOT_APP_ID=3487539
CLASSYTIC_BOT_PEM_PATH=D:/credentials/classytic-bot.pem

Vars already set in the shell / CI env are never overwritten — real secret stores always win over on-disk .env values. A per-repo .env.local naturally overrides the workspace .env because the walk starts from the nearest directory.

Supported format: KEY=value, KEY="quoted", KEY='quoted', # comments, blank lines. Not supported: variable expansion ($OTHER), multiline values.

In GitHub Actions

Wire the org-level secrets you already set up:

- name: Push as classytic-bot
  env:
    CLASSYTIC_BOT_APP_ID: ${{ vars.CLASSYTIC_BOT_APP_ID }}
    CLASSYTIC_BOT_PEM:    ${{ secrets.CLASSYTIC_BOT_PRIVATE_KEY }}
  run: npx classytic-push main

Locally

export CLASSYTIC_BOT_APP_ID=3487539
export CLASSYTIC_BOT_PEM_PATH=/path/to/classytic-bot.pem
npx classytic-push main

Or commit the env vars into a .env file (gitignored) and source .env before releasing.

Programmatic API

The binary is a thin wrapper around runPush(). If you're building your own release pipeline you can call the library functions directly:

import { runPush, mintInstallationToken, parseRemote } from "@classytic/dev-tools";

const result = await runPush({
  appId: process.env.CLASSYTIC_BOT_APP_ID!,
  pem: process.env.CLASSYTIC_BOT_PEM!,
  owner: "classytic",
  branch: "main",
  extraFlags: ["--tags"],
});

console.log(`Pushed as installation ${result.installationId}`);

Also exports:

• mintInstallationToken({ appId, pem, owner }) — mint a GitHub App installation access token.
• makeAppJwt({ appId, pem }) — just the App-level JWT (if you need to hit other /app/* endpoints).
• parseRemote(url) — { owner, repo } from any GitHub remote URL shape.

Security

• Installation tokens are minted fresh per invocation, expire in ~1 hour, and are never written to disk.
• The .pem should stay secret. This package reads it but never logs it.
• On git push failure, the token is redacted from the error message before it's thrown.
• App IDs are public (Vercel's is too) — they're meant to be visible.

Commit attribution pattern

The push alone gets you "pushed by bot". For "authored by bot" on the commit itself, set git's author via env vars on the commit:

GIT_AUTHOR_NAME="classytic-bot[bot]" \
GIT_AUTHOR_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
GIT_COMMITTER_NAME="classytic-bot[bot]" \
GIT_COMMITTER_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
git commit -m "..."

For a permanent local setup (commits in D:/projects/classytic/* automatically get the bot identity), use git's includeIf with a scoped config file — see the usage notes in each classytic repo's CLAUDE.md.

License

MIT

Trademark

MIT-licensed code. "Classytic"/"arc" names + logos are trademarks of Classytic LLC — see TRADEMARK.md.