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

• HarperFast/harper#1849 — two-phase stage/activate + revert_component
• HarperFast/harper#1850 — harper deploy by_ref=true (deploy by git reference)
• HarperFast/harper#1851 — harper deploy setup=true (client-side sealed deploy credential)
• HarperFast/harper#1876 — CI token auth + harper login --for-ci
• HarperFast/harper-pro#594 — add_ssh_key generate=true (cluster-side keygen)
• HarperFast/create-harper#118 — scaffolds this flow
• HarperFast/documentation#599 — two-phase deploy docs
• HarperFast/documentation#616 — by-reference / sealed-credential / CI-auth docs

[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.

[dawsontoth]

Rebased onto main (v1.11.2) — clean, no conflicts. Two things changed in the meantime that this needed to absorb:

1. Next.js templates landed on main, and they can't use deploy-by-reference.

By-reference means the cluster clones the repo and builds on the node. Next.js can't do that today: .next is gitignored (so a git reference carries no build output) and an on-cluster build fails outright — Turbopack crashes inside a Harper worker thread (nextjs#57) and a webpack build overruns the component-load timeout (nextjs#58). That's exactly why ded2190 re-instated prebuilt: true.

So they stay on deploy-by-payload (next build && harper deploy_component .), and applySharedTemplates.js now records why they're absent from the fan-out — otherwise the omission reads as an oversight and someone "fixes" it into a broken deploy.

They do get the _github/workflow/ → _github/workflows/ fix this PR makes everywhere else. GitHub only runs workflows from the plural directory, so the one they shipped never triggered; they now have a payload-deploy workflow in the right place with the same auth wiring.

2. CI auth moved from password to token (harper#1876).

The workflows now take HARPER_CLI_TARGET + HARPER_CLI_REFRESH_TOKEN instead of HARPER_CLI_USERNAME/HARPER_CLI_PASSWORD, and the READMEs point at the pipe that sets both without the token ever reaching the screen or shell history:

harper login --for-ci | gh secret set --env-file -

Testing. template.test.js now asserts the deploy model per template, with the payload-based ones as an explicit allow-list — a newly added template fails the by-reference assertions until it's either wired up or added there with a reason, so it can't silently opt out.

Worth flagging: template.tests/template.test.js is dormant — vitest.config.js includes only template.tests/staticConfig.test.js, so these assertions don't gate PRs. I ran it directly (12/12 pass) and confirmed they aren't vacuous by flipping the allow-list to empty: exactly the two Next.js templates fail. Enabling it in CI is a separate call — it scaffolds all 12 templates — so I left the config alone.

dprint check, oxlint, and npm test (216) are clean.

[kriszyp]

This looks good. I kinda did two GPT reviews, which is probably a bit excessive, but hopefully helpful:
Overall, this is well aligned with the deployment guidance. The immutable-SHA reference model, cluster-stored clone credential, token-based CI authentication, and payload exception for Next.js all look right. It effectively implements the newer workflow from documentation#616 rather than documentation#594’s lower-level curl examples.
I have two changes before approval:
The generated commands use restart=true with replicated=true. Documentation#594 recommends restart=rolling for cluster deployments and reserves restart=true for single-node/dev use. Since the scaffolded workflow targets Fabric clusters, can we default its deployment to restart=rolling, or document why an immediate cluster-wide restart is intended?

The READMEs describe HARPER_CLI_REFRESH_TOKEN as long-lived but omit two operational constraints: CI should use a dedicated user because issuing another refresh token invalidates the existing one, and the default refresh-token lifetime is 30 days. Please add a short warning so generated pipelines do not unexpectedly break after a local login or token expiry.

The PR description also needs refreshing: it still mentions SSH, password-based CI authentication, and the superseded dependency PR numbers, while the implementation now uses git+HTTPS, sealed tokens, and harper#1850/#1851/#1876.
Finally, this should remain blocked until harper#1850 and harper#1851 land in a released CLI. The current CI proves the templates generate correctly, but it cannot exercise those unreleased commands.
_{🤖 Reviewed with GPT 5.6}

[kriszyp]

This now makes the previously inert workflow run, but it is hard-coded to npm even though create-harper detects and installs with pnpm, Yarn, Bun, and Deno too. For example, a project created with pnpm create harper commits pnpm-lock.yaml, so setup-node's npm cache cannot resolve a package lock and the following npm ci fails; the tag workflow never reaches tests or deploy. Please generate the cache/install/run setup from the detected package manager (and apply the equivalent fix to both standalone Next.js workflows), or deliberately generate an npm lockfile and document npm-only CI. Please also exercise at least one non-npm user agent in the scaffold test so this path cannot regress.