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

template-react-ssr/README.md

@@ -103,20 +103,54 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
 
 ## Deployment
 
-When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
+Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit.
 
-Come back and log in your local CLI to your cluster:
+First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it:
 
 ```sh
 harper login
 ```
 
-Then you can deploy your app to your cluster:
+### One-time setup (private repos)
+
+So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
+
+```sh
+npm run deploy:setup
+```
+
+This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid.
+
+> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed.
+
+### Deploy
 
 ```sh
 npm run deploy
 ```
 
+This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again.
+
+### Deploy automatically from CI
+
+The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
+
+```sh
+git tag v1.0.0
+git push --tags
+```
+
+Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
+
+- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
+- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy
+
+The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself.
+
+### Private npm dependencies
+
+If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential.
+
 ## Keep Going!
 
 For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs).

template-react-ssr/_github/workflows/deploy.yaml

@@ -0,0 +1,55 @@
+# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true`
+# (`npm run deploy`).
+#
+# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster
+# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a
+# moved tag), authenticating a private clone with the encrypted token you sealed once via
+# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token.
+#
+# Required repository secrets (Settings → Secrets and variables → Actions):
+#   CLI_TARGET           your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
+#   HARPER_CLI_USERNAME  a cluster user allowed to deploy
+#   HARPER_CLI_PASSWORD  that user's password
+#
+# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed.
+# See the "Deployment" section of the README for details.
+name: Deploy to Harper Fabric
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run unit tests
+        run: npm test
+      - name: Run lint
+        run: npm run lint
+      - name: Install Harper CLI
+        # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump.
+        run: npm install -g harper@^5.2.0
+      - name: Deploy
+        run: npm run deploy
+        env:
+          CLI_TARGET: ${{ secrets.CLI_TARGET }}
+          HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }}
+          HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }}

template-react-ssr/package.json

@@ -13,7 +13,8 @@
 		"test": "node --test test/*.test.js",
 		"test:watch": "node --watch --test test/*.test.js",
 		"build": "vite build",
-		"deploy": "harper deploy_component . restart=true replicated=true"
+		"deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true",
+		"deploy:setup": "harper deploy setup=true"
 	},
 	"dependencies": {
 		"@harperfast/schema-codegen": "^1.0.10",

template-react-ts-ssr/README.md

@@ -111,20 +111,54 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
 
 ## Deployment
 
-When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
+Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit.
 
-Come back and log in your local CLI to your cluster:
+First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it:
 
 ```sh
 harper login
 ```
 
-Then you can deploy your app to your cluster:
+### One-time setup (private repos)
+
+So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
+
+```sh
+npm run deploy:setup
+```
+
+This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid.
+
+> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed.
+
+### Deploy
 
 ```sh
 npm run deploy
 ```
 
+This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again.
+
+### Deploy automatically from CI
+
+The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
+
+```sh
+git tag v1.0.0
+git push --tags
+```
+
+Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
+
+- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
+- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy
+
+The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself.
+
+### Private npm dependencies
+
+If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential.
+
 ## Keep Going!
 
 For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs).

template-react-ts-ssr/_github/workflows/deploy.yaml

@@ -0,0 +1,55 @@
+# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true`
+# (`npm run deploy`).
+#
+# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster
+# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a
+# moved tag), authenticating a private clone with the encrypted token you sealed once via
+# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token.
+#
+# Required repository secrets (Settings → Secrets and variables → Actions):
+#   CLI_TARGET           your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
+#   HARPER_CLI_USERNAME  a cluster user allowed to deploy
+#   HARPER_CLI_PASSWORD  that user's password
+#
+# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed.
+# See the "Deployment" section of the README for details.
+name: Deploy to Harper Fabric
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run unit tests
+        run: npm test
+      - name: Run lint
+        run: npm run lint
+      - name: Install Harper CLI
+        # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump.
+        run: npm install -g harper@^5.2.0
+      - name: Deploy
+        run: npm run deploy
+        env:
+          CLI_TARGET: ${{ secrets.CLI_TARGET }}
+          HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }}
+          HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }}

template-react-ts-ssr/package.json

@@ -13,7 +13,8 @@
 		"test": "node --test test/*.test.ts",
 		"test:watch": "node --watch --test test/*.test.ts",
 		"build": "vite build",
-		"deploy": "harper deploy_component . restart=true replicated=true"
+		"deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true",
+		"deploy:setup": "harper deploy setup=true"
 	},
 	"dependencies": {
 		"@harperfast/schema-codegen": "^1.0.10",

template-react-ts/README.md

@@ -111,20 +111,54 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
 
 ## Deployment
 
-When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
+Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit.
 
-Come back and log in your local CLI to your cluster:
+First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it:
 
 ```sh
 harper login
 ```
 
-Then you can deploy your app to your cluster:
+### One-time setup (private repos)
+
+So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
+
+```sh
+npm run deploy:setup
+```
+
+This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid.
+
+> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed.
+
+### Deploy
 
 ```sh
 npm run deploy
 ```
 
+This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again.
+
+### Deploy automatically from CI
+
+The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
+
+```sh
+git tag v1.0.0
+git push --tags
+```
+
+Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
+
+- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
+- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy
+
+The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself.
+
+### Private npm dependencies
+
+If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential.
+
 ## Keep Going!
 
 For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs).