Open-source packages.

Three small open-source packages on npm. All are written in TypeScript, MIT licensed, and the code is on GitHub.

  • 01

    overrepo

    Command-line tool

    Manage a fleet of git repositories from one manifest.

    When a task spans several repositories, you end up juggling clones by hand. overrepo lists them once in overrepo.yaml, then clones, updates, inspects and runs commands across them: by tag, by path, or all at once.

    • Clone only what a task needs, selected by tag or path
    • context writes a Markdown summary per repository, a map AI agents can read
    • One failing repository never stops the others; timeouts and retries are built in
    npm install -g overrepo
    overrepo init             # manifest from the repos on disk
    overrepo sync             # clone everything that is missing
    overrepo status --dirty   # repos with local changes
    overrepo exec --tags backend -- git pull
    Example: overrepo
  • 02

    create-adr

    Command-line tool

    Generate Architecture Decision Records from the command line.

    An ADR only becomes a habit when starting one costs less than skipping it. create-adr finds the next number, creates docs/adr/ if it is missing, and writes a record with every section ready to fill in.

    • Numbers records in sequence: 0001, 0002, and so on, with the title as the file name
    • Each record starts as proposed, dated today, with context, decision, consequences, alternatives and links
    • Runs with npx or pnpm dlx, nothing to install
    npx create-adr "Use Postgres"
    npx create-adr "Use Postgres"
    # → docs/adr/0001-use-postgres.md
    
    npx create-adr "Adopt changesets"
    # → docs/adr/0002-adopt-changesets.md
    
    # another repository
    npx create-adr "Version the API" --path ../api
    Example: create-adr
  • 03

    stable-error

    TypeScript library

    Stable, consistent error IDs based on error messages.

    The same failure shows up under a new ID every time a user ID or a timestamp changes, so your error dashboard can’t group it. stable-error normalises the message, adds a category and a few chosen metadata keys, and turns them into an 8-character ID that stays the same.

    • Numbers, UUIDs and timestamps are replaced by placeholders before the ID is built
    • Only type, code, field, operation, service and component metadata count
    • Takes a message or an existing Error, and returns an Error with id, category and severity
    npm install stable-error
    import { createStableError } from 'stable-error';
    
    const opts = { category: 'validation' };
    const a = createStableError('User 123 not found', opts);
    const b = createStableError('User 456 not found', opts);
    
    a.id === b.id; // true
    Example: stable-error
  • More on GitHub

    GitHub profile

    The source of these packages, and everything else I publish in the open, lives on my GitHub profile. Smaller, rougher, sometimes useful.

    # every public repository
    gh repo list maximeshr --visibility public
    
    # or just open the profile
    open https://github.com/maximeshr
    Commands to browse the GitHub profile