@harperfast/skills 1.6.1 → 1.8.0

package/harper-best-practices/rules/checking-authentication.md

@@ -2,200 +2,189 @@
 name: checking-authentication
 description: How to handle user authentication and sessions in Harper Resources.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - >-
+      reference/v5/resources/resource-api.md#`getCurrentUser(): User |
+      undefined`
+    - reference/v5/resources/resource-api.md#Session and Login from a Resource
+    - reference/v5/security/jwt-authentication.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: fdd9ec3b11011490
 ---
 
 # Checking Authentication
 
-Instructions for the agent to follow when handling authentication and sessions.
+Instructions for the agent to follow when handling user authentication and session management inside Harper Resources.
 
 ## When to Use
 
-Use this skill when you need to implement sign-in/sign-out functionality, protect specific resource endpoints, or identify the currently logged-in user in a Harper application.
+Apply this rule when implementing authentication checks, login/logout flows, or token issuance inside a custom Resource. Use it any time a Resource needs to identify the current user, establish a session, or issue JWTs to clients. See [custom-resources.md](custom-resources.md) for the general Resource authoring pattern.
 
 ## How It Works
 
-1. **Configure Harper for Sessions**: Ensure `harper-config.yaml` has sessions enabled and local auto-authorization disabled for testing:
-   ```yaml
-   authentication:
-     authorizeLocal: false
-     enableSessions: true
-   ```
-2. **Implement Sign In**: Use `this.getContext().login(username, password)` to create a session:
-   ```typescript
-   async post(_target, data) {
-    const context = this.getContext();
-    try {
-      await context.login(data.username, data.password);
-    } catch {
-      return new Response('Invalid credentials', { status: 403 });
-    }
-    return new Response('Logged in', { status: 200 });
-   }
-   ```
-3. **Identify Current User**: Use `this.getCurrentUser()` to access session data:
-   ```typescript
-   async get() {
-     const user = this.getCurrentUser?.();
+1. **Check the current user** with `getCurrentUser()`. Call it inside any Resource method to retrieve the authenticated user or `undefined` if no user is authenticated. Guard protected endpoints by returning a `401` when the result is `undefined`.
+
+   ```javascript
+   async get(target) {
+     const user = this.getCurrentUser();
      if (!user) return new Response(null, { status: 401 });
      return { username: user.username, role: user.role };
    }
    ```
-4. **Implement Sign Out**: Use `this.getContext().logout()` or delete the session from context:
-   ```typescript
-   async post() {
-     const context = this.getContext();
-     await context.session?.delete?.(context.session.id);
-     return new Response('Logged out', { status: 200 });
-   }
-   ```
-5. **Protect Routes**: In your Resource, use `allowRead()`, `allowUpdate()`, etc., to enforce authorization logic based on `this.getCurrentUser()`. For privileged actions, verify `user.role.permission.super_user`.
-
-## Examples
-
-### Sign In Implementation
-
-```typescript
-async post(_target, data) {
-  const context = this.getContext();
-  try {
-    await context.login(data.username, data.password);
-  } catch {
-    return new Response('Invalid credentials', { status: 403 });
-  }
-  return new Response('Logged in', { status: 200 });
-}
-```
 
-### Identify Current User
+   The returned object exposes `username`, `role`, and `role.permission` flags.
 
-```typescript
-async get() {
-  const user = this.getCurrentUser?.();
-  if (!user) return new Response(null, { status: 401 });
-  return { username: user.username, role: user.role };
-}
-```
+2. **Enable sessions** before using session-based login. Set `authentication.enableSessions: true` in `harperdb-config.yaml`:
 
-### Sign Out Implementation
+   ```yaml
+   authentication:
+     enableSessions: true
+   ```
 
-```typescript
-async post() {
-  const context = this.getContext();
-  await context.session?.delete?.(context.session.id);
-  return new Response('Logged out', { status: 200 });
-}
-```
+3. **Access login and session helpers** via `getContext()`. The context object exposes `context.login` and `context.session` for sign-in/out flows.
+   - Call `context.login(username, password)` to verify credentials and establish a session cookie on success.
+   - To end a session, delete it via `context.session.delete(context.session.id)`.
+
+4. **Implement sign-in and sign-out Resources** using the context helpers:
+
+   ```javascript
+   export class SignIn extends Resource {
+   	async post(_target, data) {
+   		const context = this.getContext();
+   		try {
+   			await context.login(data.username, data.password);
+   		} catch {
+   			return new Response('Invalid credentials', { status: 403 });
+   		}
+   		return new Response('Logged in', { status: 200 });
+   	}
+   }
 
-## Status code conventions used here
+   export class SignOut extends Resource {
+   	async post() {
+   		const context = this.getContext();
+   		if (!context.session) return new Response(null, { status: 401 });
+   		await context.session.delete(context.session.id);
+   		return new Response('Logged out', { status: 200 });
+   	}
+   }
+   ```
 
-- 200: Successful operation. For `GET /me`, a `200` with empty body means “not signed in”.
-- 400: Missing required fields (e.g., username/password on sign-in).
-- 401: No current session for an action that requires one (e.g., sign out when not signed in).
-- 403: Authenticated but not authorized (bad credentials on login attempt, or insufficient privileges).
+5. **Issue JWTs for non-browser clients** (CLI tools, mobile apps, service-to-service). Cookie-based sessions are intended for browser clients. For other clients, mint tokens programmatically using `server.operation()`:
+
+   ```javascript
+   import { Resource, server } from 'harper';
+
+   export class IssueTokens extends Resource {
+   	static async get(_target, context) {
+   		const { operation_token, refresh_token } = await server.operation(
+   			{ operation: 'create_authentication_tokens' },
+   			context,
+   			true,
+   		);
+   		return { operation_token, refresh_token };
+   	}
+
+   	static async post(_target, data) {
+   		const { username, password } = await data;
+   		if (!username || !password) {
+   			return new Response('username and password required', { status: 400 });
+   		}
+   		const { operation_token, refresh_token } = await server.operation({
+   			operation: 'create_authentication_tokens',
+   			username,
+   			password,
+   		});
+   		return { operation_token, refresh_token };
+   	}
+   }
 
-## Client considerations
+   export class RefreshJWT extends Resource {
+   	static async post(_target, data) {
+   		const { refresh_token } = await data;
+   		if (!refresh_token) {
+   			return new Response('refresh_token required', { status: 400 });
+   		}
+   		const { operation_token } = await server.operation({
+   			operation: 'refresh_operation_token',
+   			refresh_token,
+   		});
+   		return { operation_token };
+   	}
+   }
+   ```
 
-- Sessions are cookie-based; the server handles setting and reading the cookie via Harper. If you make cross-origin requests, ensure the appropriate `credentials` mode and CORS settings.
-- If developing locally, double-check the server config still has `authentication.authorizeLocal: false` to avoid accidental superuser bypass.
+   Pass `true` as the third argument to `server.operation()` when the operation should run as the current authenticated user. Omit it or pass `false` when the operation supplies its own credentials.
 
-## Token-based auth (JWT + refresh token) for non-browser clients
+6. **Configure JWT token expiry** in `harperdb-config.yaml` under the `authentication` section:
 
-Cookie-backed sessions are great for browser flows. For CLI tools, mobile apps, or other non-browser clients, it’s often easier to use **explicit tokens**:
+   ```yaml
+   authentication:
+     operationTokenTimeout: 1d
+     refreshTokenTimeout: 30d
+   ```
 
-- **JWT (`operation_token`)**: short-lived bearer token used to authorize API requests.
-- **Refresh token (`refresh_token`)**: longer-lived token used to mint a new JWT when it expires.
+   Duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`).
 
-This project includes two Resource patterns for that flow:
+## Examples
 
-### Issuing tokens: `IssueTokens`
+**Protecting a resource endpoint and returning user info:**
 
-**Description / use case:** Generate `{ refreshToken, jwt }` either:
+```javascript
+async get(target) {
+  const user = this.getCurrentUser();
+  if (!user) return new Response(null, { status: 401 });
+  return { username: user.username, role: user.role };
+}
+```
 
-- with an existing Authorization token (either Basic Auth or a JWT) and you want to issue new tokens, or
-- from an explicit `{ username, password }` payload (useful for direct “login” from a CLI/mobile client).
+**Full session-based sign-in/sign-out flow:**
 
 ```javascript
-export class IssueTokens extends Resource {
-	static loadAsInstance = false;
-
-	async get(target) {
-		const { refresh_token: refreshToken, operation_token: jwt } =
-			await databases.system.hdb_user.operation(
-				{ operation: 'create_authentication_tokens' },
-				this.getContext(),
-			);
-		return { refreshToken, jwt };
-	}
-
-	async post(target, data) {
-		if (!data.username || !data.password) {
-			throw new Error('username and password are required');
+export class SignIn extends Resource {
+	async post(_target, data) {
+		const context = this.getContext();
+		try {
+			await context.login(data.username, data.password);
+		} catch {
+			return new Response('Invalid credentials', { status: 403 });
 		}
+		return new Response('Logged in', { status: 200 });
+	}
+}
 
-		const { refresh_token: refreshToken, operation_token: jwt } =
-			await databases.system.hdb_user.operation({
-				operation: 'create_authentication_tokens',
-				username: data.username,
-				password: data.password,
-			});
-		return { refreshToken, jwt };
+export class SignOut extends Resource {
+	async post() {
+		const context = this.getContext();
+		if (!context.session) return new Response(null, { status: 401 });
+		await context.session.delete(context.session.id);
+		return new Response('Logged out', { status: 200 });
 	}
 }
 ```
 
-**Recommended documentation notes to include:**
-
-- `GET` variant: intended for “I already have an Authorization token, give me new tokens”.
-- `POST` variant: intended for “I have credentials, give me tokens”.
-- Response shape:
-  - `refreshToken`: store securely (long-lived).
-  - `jwt`: attach to requests (short-lived).
-
-### Refreshing a JWT: `RefreshJWT`
-
-**Description / use case:** When the JWT expires, the client uses the refresh token to get a new JWT without re-supplying username/password.
+**JWT token refresh endpoint:**
 
 ```javascript
 export class RefreshJWT extends Resource {
-	static loadAsInstance = false;
-
-	async post(target, data) {
-		if (!data.refreshToken) {
-			throw new Error('refreshToken is required');
+	static async post(_target, data) {
+		const { refresh_token } = await data;
+		if (!refresh_token) {
+			return new Response('refresh_token required', { status: 400 });
 		}
-
-		const { operation_token: jwt } = await databases.system.hdb_user.operation({
+		const { operation_token } = await server.operation({
 			operation: 'refresh_operation_token',
-			refresh_token: data.refreshToken,
+			refresh_token,
 		});
-		return { jwt };
+		return { operation_token };
 	}
 }
 ```
 
-**Recommended documentation notes to include:**
-
-- Requires `refreshToken` in the request body.
-- Returns a new `{ jwt }`.
-- If refresh fails (expired/revoked), client must re-authenticate (e.g., call `IssueTokens.post` again).
-
-### Suggested client flow (high-level)
-
-1. **Sign in (token flow)**
-   - POST /IssueTokens/ with a body of `{ "username": "your username", "password": "your password" }` or GET /IssueTokens/ with an existing Authorization token.
-   - Receive `{ jwt, refreshToken }` in the response
-2. **Call protected APIs**
-   - Send the JWT with each request in the Authorization header (as your auth mechanism expects)
-3. **JWT expires**
-   - POST /RefreshJWT/ with a body of `{ "refreshToken": "your refresh token" }`.
-   - Receive `{ jwt }` in the response and continue
-
-## Quick checklist
+## Notes
 
-- [ ] Public endpoints explicitly `allowRead`/`allowCreate` as needed.
-- [ ] Sign-in uses `context.login` and handles 400/403 correctly.
-- [ ] Protected routes call `ensureSuperUser(this.getCurrentUser())` (or another role check) before doing work.
-- [ ] Sign-out verifies a session and deletes it.
-- [ ] `authentication.authorizeLocal` is `false` and `enableSessions` is `true` in Harper config.
-- [ ] If using tokens: `IssueTokens` issues `{ jwt, refreshToken }`, `RefreshJWT` refreshes `{ jwt }` with a `refreshToken`.
+- `getCurrentUser()` and `getContext()` are instance methods; call them with `this` inside non-static Resource methods.
+- `enableSessions` must be `true` in config before `context.login` or `context.session` will function.
+- Cookie-based sessions target browser clients. Use JWT issuance via `server.operation()` for all other client types.
+- When both `operation_token` and `refresh_token` have expired, the client must call `create_authentication_tokens` again with credentials.

package/harper-best-practices/rules/creating-harper-apps.md

@@ -7,11 +7,14 @@ metadata:
 
 # Creating Harper Applications
 
-The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command initializes a project with a standard folder structure, essential configuration files, and basic schema definitions.
+The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command
+initializes a project with a standard folder structure, essential configuration files, and basic
+schema definitions.
 
 ## When to Use
 
-Use this command when starting a new Harper application or adding a new Harper microservice to an existing architecture.
+Use this command when starting a new Harper application or adding a new Harper microservice to an
+existing architecture.
 
 ## Commands
 

package/harper-best-practices/rules/deploying-to-harper-fabric.md

@@ -2,103 +2,121 @@
 name: deploying-to-harper-fabric
 description: How to deploy a Harper application to the Harper Fabric cloud.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/components/applications.md#Remote Management
+    - >-
+      fabric/cluster-creation-management.md#Connecting the Harper CLI to a
+      Cluster
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: ccdefbbf8f3b8657
 ---
 
 # Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying to Harper Fabric.
+Instructions for the agent to follow when deploying a Harper application to the Harper Fabric cloud using the Harper CLI.
 
 ## When to Use
 
-Use this skill when you are ready to move your Harper application from local development to a cloud-hosted environment.
+Apply this rule when deploying a Harper application to a remote Harper instance or Harper Fabric cluster. This covers interactive deployments, CI/CD pipelines, and any scenario where the agent must push a local or remote package to a target environment.
 
 ## How It Works
 
-1. **Sign up**: Follow the [creating-a-fabric-account-and-cluster](creating-a-fabric-account-and-cluster.md) rule to create a Harper Fabric account, organization, and cluster.
-2. **Configure Environment**: Add your cluster credentials and cluster application URL to `.env`:
+1. **Authenticate with the remote target**: Run `harper login` once to store an authentication token. The CLI writes `HARPER_CLI_TARGET` to a local `.env` so subsequent commands do not need credentials repeated. Find the **Application URL** on the cluster's **Config → Overview** page (see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md)).
+
+   ```bash
+   harper login <Application URL>
+   # Provide cluster username and password when prompted
+   ```
+
+2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials are needed inline.
+
+   ```bash
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
+
+3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and deploy the current local directory.
+
+   | Value                                                | Effect                                           |
+   | ---------------------------------------------------- | ------------------------------------------------ |
+   | _(omitted)_                                          | Packages and deploys the current local directory |
+   | `"@harperdb/status-check"`                           | npm package                                      |
+   | `"HarperDB/status-check"`                            | GitHub repo (short form)                         |
+   | `"https://github.com/HarperDB/status-check"`         | GitHub repo (full URL)                           |
+   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                             |
+   | `"https://example.com/application.tar.gz"`           | Remote tarball                                   |
+
+   For git tags, use the `semver` directive for reliable versioning:
+
+   ```
+   HarperDB/application-template#semver:v1.0.0
+   ```
+
+4. **Authenticate for CI/CD pipelines**: Use environment variables instead of interactive login. Set credentials before running `harper deploy`.
+
    ```bash
-   CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'
-   CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'
-   CLI_TARGET='YOUR_CLUSTER_URL'
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
    ```
-3. **Deploy From Local Environment**: Run `npm run deploy`.
-4. **Set up CI/CD**: Configure `.github/workflows/deploy.yaml` and set repository secrets for automated deployments.
 
-## Manual Setup for Existing Apps
+5. **Register SSH keys for private repos**: Before deploying from an SSH-based private repository, use the Add SSH Key operation to register the key with the remote instance.
+
+## Examples
 
-If your application was not created with `npm create harper`, you'll need to manually configure the deployment scripts and CI/CD workflow.
+**Interactive login then deploy (recommended):**
 
-### 1. Update `package.json`
+```bash
+# Log in once
+harper login <remote>
+# Provide your username and password when prompted
 
-Add the following scripts and dependencies to your `package.json`:
+# Subsequently deploy without credentials
+harper deploy \
+  project=<name> \
+  package=<package> \
+  target=<remote> \
+  restart=true \
+  replicated=true
+```
 
-```json
-{
-	"scripts": {
-		"deploy": "dotenv -- npm run deploy:component",
-		"deploy:component": "harper deploy_component . restart=rolling replicated=true"
-	},
-	"devDependencies": {
-		"dotenv-cli": "^11.0.0",
-		"harper": "^5.0.0"
-	}
-}
+**Deploy with inline credentials (not recommended for production):**
+
+```bash
+harper deploy \
+  project=<name> \
+  package=<package> \
+  username=<username> \
+  password=<password> \
+  target=<remote> \
+  restart=true \
+  replicated=true
 ```
 
-#### Why split the scripts?
-
-The `deploy` script is separated from `deploy:component` to ensure environment variables from your `.env` file are properly loaded and passed to the Harper CLI.
-
-- `deploy`: Uses `dotenv-cli` to load environment variables (like `CLI_TARGET`, `CLI_TARGET_USERNAME`, and `CLI_TARGET_PASSWORD`) before executing the next command.
-- `deploy:component`: The actual command that performs the deployment.
-
-By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harper deploy_component` is called, allowing it to authenticate with your cluster.
-
-### 2. Configure GitHub Actions
-
-Create a `.github/workflows/deploy.yaml` file with the following content:
-
-```yaml
-name: Deploy to Harper Fabric
-on:
-  workflow_dispatch:
-#  push:
-#    branches:
-#      - main
-concurrency:
-  group: main
-  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: Deploy
-        run: npm run deploy
-        env:
-          CLI_TARGET: ${{ secrets.CLI_TARGET }}
-          CLI_TARGET_USERNAME: ${{ secrets.CLI_TARGET_USERNAME }}
-          CLI_TARGET_PASSWORD: ${{ secrets.CLI_TARGET_PASSWORD }}
+**Deploy a specific GitHub release by semver tag:**
+
+```bash
+harper deploy \
+  project=my-app \
+  package="HarperDB/application-template#semver:v1.0.0" \
+  target=<remote> \
+  restart=true \
+  replicated=true
 ```
 
-Be sure to set the following repository secrets in your GitHub repository's /settings/secrets/actions:
+## Notes
 
-- `CLI_TARGET`
-- `CLI_TARGET_USERNAME`
-- `CLI_TARGET_PASSWORD`
+- Always prefer `harper login` for interactive use and environment variables (`HARPER_CLI_USERNAME`, `HARPER_CLI_PASSWORD`) for CI/CD. Avoid inline `username`/`password` parameters in production.
+- Omitting `package` causes the CLI to package the current local directory. Specifying a local file path creates a symlink, so changes are picked up between restarts without redeploying.
+- Harper generates a `package.json` from component configurations and resolves dependencies using a form of `npm install`.
+- For SSH-based private repos, register keys with the Add SSH Key operation before deploying.

package/harper-best-practices/rules/load-env.md

@@ -0,0 +1,100 @@
+---
+name: load-env
+description: >-
+  How to load environment variables from .env files into a Harper application
+  using the loadEnv plugin.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/environment-variables/overview.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: c73a0caf28a2b833
+---
+
+# Load Environment Variables with loadEnv
+
+Instructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.
+
+## When to Use
+
+Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever you need to configure `loadEnv` in `config.yaml`, control load order, handle multiple files, or manage override behavior.
+
+## How It Works
+
+1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` to your `config.yaml` with a `files` key pointing to the `.env` file. `loadEnv` is built into Harper and does not need to be installed separately.
+
+   ```yaml
+   loadEnv:
+     files: '.env'
+   ```
+
+   This loads the specified file from the root of your component directory into `process.env`.
+
+2. **Place `loadEnv` first**: Always declare `loadEnv` before any other components in `config.yaml` so environment variables are available before dependent components start. Because Harper is single-process, variables loaded onto `process.env` are shared across all components.
+
+   ```yaml
+   # config.yaml — loadEnv must come first
+   loadEnv:
+     files: '.env'
+
+   rest: true
+
+   myApp:
+     files: './src/*.js'
+   ```
+
+3. **Control override behavior**: By default, existing shell or container environment variables take precedence over values in `.env` files. To force `.env` values to overwrite existing variables, set `override: true`.
+
+   ```yaml
+   loadEnv:
+     files: '.env'
+     override: true
+   ```
+
+4. **Load multiple files**: Provide a list of files or a glob pattern under `files`. Files are loaded in the order specified.
+   ```yaml
+   loadEnv:
+     files:
+       - '.env'
+       - '.env.local'
+   ```
+   Or using a glob pattern:
+   ```yaml
+   loadEnv:
+     files: 'env-vars/*'
+   ```
+
+## Examples
+
+A complete `config.yaml` using `loadEnv` with multiple files and override enabled:
+
+```yaml
+# config.yaml — loadEnv must come first
+loadEnv:
+  files:
+    - '.env'
+    - '.env.local'
+  override: true
+
+rest: true
+
+myApp:
+  files: './src/*.js'
+```
+
+A minimal setup loading a single `.env` file:
+
+```yaml
+loadEnv:
+  files: '.env'
+
+myApp:
+  files: './src/*.js'
+```
+
+## Notes
+
+- `loadEnv` is built into Harper — declare it in `config.yaml` only; do not install it as a separate package.
+- The `files` value accepts either a single string, a list of strings, or a glob pattern.
+- Without `override: true`, variables already present in the environment are never overwritten by values in `.env` files.
+- `process.env` is shared across all Harper components in the same process, so load order in `config.yaml` determines availability.