feat: deploy-by-reference via native harper CLI (prototype / draft)

[dawsontoth]

Draft / prototype. This is what create-harper's deploy scaffolding looks like once native harper CLI support lands. It deliberately uses CLI features that aren't released yet, so it can't merge until they do — see Blocked on below.

What this shows

The end-state of the deploy-by-reference switch (create-harper#117): scaffolded projects deploy by reference (the Harper cluster clones a pinned commit over SSH) with no per-project scripts.

• package.json: deploy → harper deploy by_ref=true restart=true replicated=true; deploy:setup → harper deploy setup=true.
• Centralized GitHub Actions workflow at .github/workflows/deploy.yaml — also fixes a latent bug: templates shipped a singular _github/workflow/ that GitHub never runs; now workflows/ (plural). Tag- and dispatch-triggered.
• .env carries only CLI_TARGET; credentials come from harper login (local) or GitHub Actions secrets CLI_TARGET / HARPER_CLI_USERNAME / HARPER_CLI_PASSWORD (CI).
• README "Deployment" sections rewritten around the reference model + rollback.

Relationship to the ships-today version

The interim version that works with the currently released CLI carries scripts/deploy.mjs + scripts/setup-deploy.mjs (the logic lives in the project until the CLI can do it natively). It's on branch claude/harper-deployment-path-dd2495. This PR is the same feature with those scripts folded into the CLI.

Blocked on (must release first)

• CLI: harper deploy by_ref=true — deploy by git reference harper#1777 — harper deploy by_ref=true (prototyped, branch claude/deploy-by-ref-flag)
• CLI: harper deploy --setup — one-command deploy-key provisioning harper#1778 — harper deploy setup=true
• add_ssh_key: server-side keygen via generate: true harper-pro#570 — add_ssh_key generate=true (drafted, branch claude/add-ssh-key-generate)

Tracks create-harper#117. Rollback: HarperFast/harper#641.

Notes

• deploy:setup spelling (setup=true vs --setup vs a dedicated harper add-deploy-key) is TBD per harper#1778; this PR uses setup=true to match the CLI's key=value arg model.
• npm test (213 tests) green; dprint + oxlint clean.

🤖 Generated with Claude Code

---

Related — deploy-by-reference effort

Prototype PRs: HarperFast/harper#1850 (deploy by_ref) · HarperFast/harper#1851 (deploy setup) · HarperFast/harper-pro#594 (add_ssh_key generate) · #118 (create-harper scaffold)

Tracking issues: HarperFast/harper#1777 · HarperFast/harper#1778 · HarperFast/harper-pro#570 · #117 · HarperFast/harper#641 (rollback)

[gemini-code-assist]

Code Review

This pull request updates the deployment process across multiple project templates to deploy "by reference" using the native harper CLI. It adds a new GitHub Actions workflow (deploy.yaml), updates package.json scripts to include deploy and deploy:setup, and updates the documentation in README.md files. Feedback on these changes highlights that the template-early-hints template was only partially updated, missing changes to its package.json and README.md. Additionally, installing the harper CLI globally in the workflow without a version pin could introduce breaking changes in the future, and the duplication of the deploy.yaml file across all template directories should be addressed by dynamically copying it from a centralized location.

[gemini-code-assist]

There is significant duplication of the deploy.yaml workflow file across all 11 template directories and templates-shared/all.\n\nIf there is an automated build/prepare script that copies files from templates-shared/all into each template directory, these duplicated files in the individual template folders should ideally be gitignored or not committed manually to avoid drift.\n\nIf there is no such script, consider introducing a step in the scaffolding process (e.g., in scaffoldProject.js) to copy shared files from templates-shared/all dynamically, which would allow you to delete the 11 duplicate copies and maintain the workflow in a single centralized place.

[dawsontoth]

No. We commit them to make them easy for humans to discover when browsing the repo.

[dawsontoth]

Leaving the per-template copies as-is — committing the fanned-out shared files into each template is intentional in this repo (see templates-shared/README.md): it keeps them discoverable when browsing and lets the scaffolder copy a template directory wholesale with no merge step. applySharedTemplates.js is the sync mechanism, so there's no manual drift. Flagging for a human maintainer rather than resolving, in case you'd prefer a different model.

🤖 Addressed by Claude Code