Skip to content

Latest commit

 

History

History
255 lines (209 loc) · 12.7 KB

developer-workflow.md

File metadata and controls

255 lines (209 loc) · 12.7 KB

Developer workflow

Documentation · Project overview

Run project commands from the relevant checkout. This setup supplies shared tools; each project keeps its own runtime version, package manager, dependencies, tasks, and credentials.

Activate new helpers in an existing installation

After the changes are merged, update your persistent installation checkout and refresh its configuration links:

cd ~/linux-setup                 # Use your actual installation checkout
git pull --ff-only
./install.sh --config-only --skip-mcp
exec zsh

Use the persistent checkout for installation, rather than a temporary review worktree. Configuration-only installation keeps existing tools and their versions.

Git and GitHub profiles

Run ./install.sh --github-setup from the setup checkout to fill missing global Git author settings, install GitHub CLI if needed, and add accounts. You can also run git-profile add later: it offers GitHub CLI login, or you can reuse an account already logged in. Add each GitHub username with its commit author name and email, then use:

git-profile list
cd ~/projects/my-repository
git-profile use my-github-username

use selects the account in GitHub CLI and sets user.name and user.email for the current repository. GitHub CLI's active account is shared across terminal sessions for that host, so switching accounts affects other repositories and terminals too; their saved repository author settings do not change. Run gh auth status to inspect accounts. HTTPS Git credentials use the GitHub CLI account only if its credential helper is configured (for example, with gh auth setup-git); SSH authentication depends on your SSH configuration. Environment tokens such as GH_TOKEN can override saved GitHub CLI accounts. GitHub CLI manages credentials separately and may store tokens in a plain-text file if no credential store is available. The profile file contains only author details and usernames, not tokens. Use an email associated with the intended GitHub account, including its no-reply address if desired.

AI skills

Run skill-manager to install, list, or remove local skills. From a checkout that has not been installed, run python3 scripts/skill_manager.py instead. Select Codex or Claude Code, then global or project scope. For project scope, provide the path of an existing project directory; enter . to use the current directory. The install menu groups the catalog by work area and accepts multiple selections.

Agent Global directory Project directory
Codex ~/.agents/skills/ <project>/.agents/skills/
Claude Code ~/.claude/skills/ <project>/.claude/skills/

These are local agent skills, not skills uploaded to ChatGPT or another hosted service. The manager lists and removes skill directories in the selected location, including skills installed by other tools; it displays the exact paths and asks for confirmation before deleting. It does not overwrite existing skills. Skills installed as symlinks are removed by unlinking them; their targets are kept. Skills in other discovery locations, such as ~/.codex/skills, are not listed there.

The catalog includes UI/UX Pro Max, Humanizer, frontend design, web guidelines, React, testing, DevOps, and writing skills. OpenAI's Codex-specific skills are offered only for Codex. The catalog records upstream repositories and commit IDs in skills.catalog.json. Downloads need network access; files are then installed locally with their supporting resources. UI/UX Pro Max's plugin-specific script paths are adapted to the selected installation directory, so reinstall it after moving that directory. Review the displayed source URLs: third-party skills contain instructions and may include scripts. Restart the agent session if it does not immediately discover new skills.

Check a checkout

dev-check                       # Read-only checks for the current project
dev-check ../another-project     # Check another checkout
dev-check --json                 # Machine-readable results
dev-check --network              # Also probe registry reachability
linux-doctor                    # Check the terminal setup itself

dev-check inspects manifests, lockfiles, dependency markers, Git checkout status, and tool availability. A Compose filename enables a local Docker check. It does not install packages, start services, source dotenv files, or run project tasks. The optional npm registry probe requires --network.

JSON ready: true and exit status 0 mean no failure was detected. Review warnings and skipped checks: PnP dependencies and remote Docker contexts can remain unverified. Follow the reported next steps in the project's own setup guide.

Find and review work

Command Use
rg --files List project files using ignore rules
fd config Find paths matching a name
rg -n 'pattern' src tests Search selected source directories
jq '.scripts' package.json Inspect JavaScript project tasks
git status --short --branch Review branch and local changes
git diff, git diff --staged Review pending and staged changes
git worktree list Locate other checkouts of the repository
lg Open the installed Git interface

Run project tasks

Use the repository's pinned runtime and package manager. vp supports the JavaScript workflow; projects can also call their selected manager directly. Examples below assume those task names exist:

vp install                      # Install the project's dependencies
vp run dev
vp run test
vp run typecheck
pnpm env:check                  # When the project defines this Varlock task
uv sync                        # Install a Python project's locked environment
uv run pytest                  # When pytest belongs to that project

Keep Varlock schemas and application-specific scripts in their projects. A shared shell helper should not choose new dependency versions or copy a project's secrets into global configuration. In this repository, the Python check is python3 -m unittest discover -s tests -v; see development checks for the complete maintenance workflow.

Prepare browser tests

Install the project's dependencies first so its pinned Playwright package is available. From that project, use:

dev-browser doctor
dev-browser install --user-deps
dev-browser run -- pnpm test:e2e

doctor reports installed paths and launches and closes headless Chromium to check that it works. install downloads the Chromium version selected by the project's Playwright package; it does not install or upgrade Playwright globally. Omit --user-deps when the host already provides the required libraries. The initial supported browser workflow is headless Chromium.

On Ubuntu/Debian, --user-deps explicitly downloads and extracts APT packages into ${XDG_CACHE_HOME:-~/.cache}/linux-setup/browser-deps. It does not use sudo or update APT indexes, so package indexes must already be available. Chromium itself uses Playwright's normal browser cache. Extracted libraries and fonts apply only to commands launched by the helper; your shell's global library configuration stays unchanged. run returns that command's exit code.

Rootless installation accepts only the recognized Playwright dependency-report format. An unfamiliar or older dry-run format stops before APT downloads; follow the displayed administrator-assisted playwright install-deps chromium guidance instead. The helper does not upgrade Playwright to change its output.

Replace pnpm test:e2e with the project's actual browser-test command. Use dev-browser --project /path/to/project doctor to target another checkout. The browser helper does not read dotenv files itself; it executes the project's installed Playwright and your chosen test command. On hosts without the supported APT workflow, use the administrator-managed system dependencies documented by Playwright. The optional browser dependency cache can be selected for removal in the uninstaller; ordinary uninstall keeps it.

Inspect local services

lip 3001 5173                    # List listeners for an API and web server
kip 5173                        # Confirm before stopping the matching process
docker compose ps               # Inspect this project's Compose services
db --connections                # List redacted .env targets without connecting
db .env.local --connections      # Select a different dotenv file explicitly
db --var TEST_DATABASE_URL       # Open the interactive manager for that target

The database helper discovers TEST_DATABASE_URL and TEST_DB_URL alongside the usual DATABASE_URL/DB_URL names. It parses the selected file as data and does not source shell commands. db --connections is an inspection command; the interactive manager also offers database changes with confirmation. Keep test URLs pointed at disposable databases. Installing psql does not start a database server.

Discover and use custom commands

Press Alt+X (both lowercase and uppercase x work) or run devcommands to open the fzf picker. Type part of a shortcut, its description, or its full command. The preview includes the full definition, even for multiline functions. Ctrl-/ toggles the preview. Enter inserts the selection into the editable prompt and does not execute it. An alias inserts its expansion; a function inserts its name and a trailing space so you can supply arguments. Selecting replaces the current line; Escape or Ctrl-C preserves the line and cursor. The binding works in Emacs and vi keymaps. If your terminal uses Alt+X for a menu, use Escape then x or the devcommands command.

devcommands docker              # Open with an initial search
devhelp                         # Print the current reference without fzf
devhelp pnpm                    # Filter the printed reference by text

The picker uses live shell definitions and description comments from config/zsh/aliases.zsh, functions.zsh, command-picker.zsh, and private linux-setup-local/zshrc / zshenv. It excludes internal helper functions and shortcuts that were not loaded, including conditional aliases for absent tools. It does not call any of the commands to build the list. Regular aliases and named functions declared in these files are supported; dynamically generated commands and commands in other sourced files are outside this catalogue.

Included shortcuts:

Group Examples
Project scripts and dependencies pscripts, pd, pb, pt, pcheck, pr TASK, pi, pif, pa, pad, px, pfilter
Vite+ vpi, vr TASK, vcheck, vfmt, vtest, vwatch
Rust and Laravel cgb, cgc, cgt, cgr, cgl, cgrelease, art, arts, artt, sail
Git and GitHub gfind TEXT, gbranches, gconflicts, gpull, ghprs, ghpr, ghchecks, ghruns
Containers dctx, dctxs, duse, dpsa, dccheck, dcservices, dcup, dcstop, dclog, dsh, dcsh
Kubernetes and Terraform kctx, kcontexts, kuse, kpods, klogs, kdesc, tfinit, tfvalidate, tffmtcheck, tfplan
Host and network disks, mem, dus, listens, ipbrief, svcfailed, jerrors, junit, httpcheck, sshtunnel
PostgreSQL and JSON pgconnect SERVICE, pg-local, pg-remote, pg-bingo, jpretty, jcompact
AI agents and project checks cx, cxr, cxc, cxe, cld, cldr, cldc, dcheck, dbr

Project script names must exist in package.json; use pscripts to inspect them. Direct Vite+ tools can bypass a project's wrappers, so use pcheck and pt for its full check/test scripts. Container commands use the active Docker context; dsh CONTAINER [SHELL] and dcsh SERVICE [SHELL] default to sh. Existing Docker reset shortcuts and dc help remain available, including their volume-deleting operations. PostgreSQL shortcuts use profiles you configure privately in ~/.pg_service.conf, with normal password prompt or ~/.pgpass authentication. Kubernetes, Terraform, GitHub, Docker, language tools, and agent CLIs must be installed separately if missing; adding an alias does not install its target.

For private additions, put a comment immediately above each alias or function in ~/.config/linux-setup-local/zshrc, then run reload:

# Follow this project's API logs.
alias apilogs='docker compose logs --follow api'

# Check the current project's package scripts.
project_scripts() { command jq '.scripts // {}' package.json; }

Keep credentials in the appropriate project's ignored files or configured secret provider. Paid UI registry keys belong only in their component-install workflow, with no VITE_ prefix and no browser import. Use the project's redacted configuration checks when sharing diagnostics.