README

A tool to download database dumps and assets of available environments.

dev-note ships as a single self-contained macOS binary (Apple Silicon / arm64) that embeds its own PHP runtime. No PHP installation is required to run it.

Install

Download the dev-note binary into a directory on your PATH that you can write to (e.g. ~/bin or ~/.local/bin), make it executable, and run it:

chmod +x dev-note
dev-note list

Keep it up to date with the built-in self-updater:

dev-note update

Runtime requirements

The binary bundles PHP, but it shells out to standard tools that must exist on your system:

ssh, rsync (remote transfer)
docker (only for db:import into the local container MySQL)

Build

Builds the native binary. Requires Docker (phar stage) and a macOS arm64 host with the Xcode command line tools + Homebrew (binary stage). The first build compiles a static PHP from source and takes a while; later builds are fast.

sh bin/build.sh

Versioning

The version lives in one place: the version field in composer.json. The build stamps it into the binary (dev-note --version) and the update manifest. To release a new version, bump that field, then build/publish.

Publish

Build the binary and push it to the update server (what dev-note update pulls from). Needs the build toolchain plus S3 credentials; publishing prompts for confirmation (-y to skip):

S3_ACCESS_KEY=… S3_SECRET_KEY=… sh bin/publish.sh

It first runs the full quality gate — phplint, php-cs-fixer (dry-run), phpstan, unit and e2e tests — and aborts if anything fails, so a broken or unformatted build never ships (emergency override: PUBLISH_SKIP_QA=1). Then it uploads dev-note + dev-note.sha256 (the manifest: line 1 = version, line 2 = SHA-256) to s3://phar via s3cmd in Docker. Override S3_BUCKET, or set S3_HOST/S3_HOST_BUCKET for a non-AWS endpoint. The legacy phar's dev-note.version is left untouched so old phar clients keep working during migration.

Release builds happen here, not in CI: the native binary can't be cross-built on Linux, so GitLab only runs the MR quality gates (lint, phpstan, unit).

Commands

dev-note runs from inside a project directory that has a Deployer file (.ci/deployer/deploy.php, .ci/deployer/config.php, or deploy.php); it reads the environments from there. List everything:

dev-note list

Command	What it does
`env:list`	List the environments found in the Deployer file.
`env:get <env>`	Download the remote `.env` as `.env.<env>`.
`db:dump <env> [name]`	Dump the remote database locally (`--import`/`-i` to also import).
`db:import <file>`	Import a dump into the local `db` container MySQL.
`rsync:get <env> [folder]`	Sync a shared folder down (defaults to `fileadmin`).
`rsync:list <env>`	List the shared folders on the remote.
`rsync:size <env> [folder]`	Show the size of a remote shared folder.
`typo3:ext`	List installed TYPO3 extensions from `composer.lock`.
`shell <env>`	Open an interactive SSH shell in the environment's current release.
`update`	Self-update the binary to the latest published version.

Pass an SSH key explicitly with --private-key /path/to/key (-k); otherwise the usual ~/.ssh keys are tried.

dev-note db:dump staging --import
dev-note rsync:get staging fileadmin

shell

Logs you into an environment without looking up host, user or port: they come from the Deployer file, the same source as every other command.

dev-note shell staging

The session starts in the live release (<deploy_path>/current, falling back to <deploy_path> when the symlink is missing) and runs your remote login shell, so aliases and profile are loaded. Exiting the shell returns you to your local prompt with the remote exit code.

Identity handling differs from the transfer commands on purpose: without -k no key is forced, so ssh resolves it exactly like a hand-typed ssh call — ~/.ssh/config, ssh-agent, then the default key files. Force one when you need to:

dev-note shell staging --private-key ~/.ssh/id_project

Unknown hosts are accepted on first connect, but a changed host key aborts the connection. Add -v to print the exact ssh command before connecting.

Development

Quality tooling runs in Docker via Composer scripts (only host dependency is Docker):

composer analyze   # phpstan (level 8)
composer lint      # phplint
composer fix       # php-cs-fixer

Tests

composer unit      # unit suite (tests/Unit), fast, no Docker services
composer e2e       # end-to-end suite (tests/E2E): spins up sshd + MariaDB + a runner,
                   # drives the real commands, tears the stack down.
                   # Needs Docker and ssh-keygen (run.sh generates a throwaway key first).

Run a single unit test:

.ci/scripts/console.sh -s unit -e "--filter testMethodName"

The binary self-update path has its own macOS release-gate script (run after sh bin/build.sh):

sh tests/E2E/binary-update.sh

psvneo / tool-dev-note

Maintainers

Package info

Statistics

Security