@siloy/hubspot-provisioning 0.1.1 → 0.1.2

package/README.md

@@ -7,7 +7,7 @@ Requires Node 20 or newer.
 ## Install
 
 ```sh
-npx -y @siloy/hubspot-provisioning@0.1.1 validate
+npx -y @siloy/hubspot-provisioning@0.1.2 validate
 ```
 
 In CI, run this pinned `npx` form (see "GitHub Actions"); don't install the CLI as a repo dependency in a job that has the deploy key. For editor support of the schema, a local install is fine: `npm install --save-dev @siloy/hubspot-provisioning`.
@@ -44,7 +44,7 @@ hubspot-provisioning deploy [file] [plan options except --mode]
 On a `pull_request` event, `GITHUB_SHA` and `GITHUB_REF` are the merge commit and `refs/pull/N/merge`, not your branch. That is what the plan is recorded under unless you pass the head yourself:
 
 ```yaml
-- run: npx -y @siloy/hubspot-provisioning@0.1.1 plan --mode preview --sha "$HEAD_SHA" --ref "$HEAD_REF"
+- run: npx -y @siloy/hubspot-provisioning@0.1.2 plan --mode preview --sha "$HEAD_SHA" --ref "$HEAD_REF"
   env:
     npm_config_registry: https://registry.npmjs.org
     HEAD_SHA: ${{ github.event.pull_request.head.sha }}
@@ -72,7 +72,9 @@ Pass them through `env:`, never inline in the `run:` text: a branch name is atta
 
 ## Getting a deploy key
 
-A deploy key belongs to a workspace and is bound to one portal and blueprint. A workspace owner creates it on the blueprint page in the provisioning app and either:
+A deploy key belongs to a workspace and is bound to one portal and blueprint. It is either "Preview only" (it can run `plan --mode preview` and nothing else) or "Preview and deploy". Use a preview-only key in the pull-request job and the deploy key only in the job that runs on `main`: two secrets, `PROVISIONING_PREVIEW_KEY` and `PROVISIONING_KEY` in the samples below. A preview-only key gets `preview_only_key` (exit 1) for a deploy plan or an apply. Its previews compare with what the deploy key last deployed to the portal, so they flag the same hand edits in HubSpot a deploy would. This needs exactly one deploy key (not revoked) for the blueprint and portal; with several, previews block every update.
+
+A workspace owner creates a key on the blueprint page in the provisioning app, chooses its access, and either:
 
 - copies the secret and puts it in the repo's CI secrets, or
 - chooses "Create a link for a developer" and sends you the link. The link works once and expires. Open it, click "Reveal secret" and copy the `hspk_` secret into the repo's CI secrets. If the link expired unused, ask the owner for a new one. If it was already opened (by you or someone else), the owner revokes the key and creates a new one.
@@ -83,7 +85,7 @@ A key expires after 90 days without use, counted from its last use, creation or
 
 ## GitHub Actions
 
-Preview on pull requests (with a comment that is updated, not repeated) and deploy on pushes to `main`. Pin the actions by commit SHA as your own policy requires; versions are shown here for readability. The samples pin 0.1.1; pin the version you use and bump it on purpose.
+Preview on pull requests (with a comment that is updated, not repeated) and deploy on pushes to `main`. Pin the actions by commit SHA as your own policy requires; versions are shown here for readability. The samples pin 0.1.2; pin the version you use and bump it on purpose.
 
 ```yaml
 # .github/workflows/blueprint.yml
@@ -109,13 +111,13 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: 24
-      # No npm ci: the job holds the deploy key, so it runs only the pinned CLI, never the branch's dependencies.
+      # No npm ci: the job holds a key (the preview-only one, which can still plan and read the portal), so it runs only the pinned CLI, never the branch's dependencies.
       # npm_config_registry outranks a project .npmrc, so a branch cannot point npx at another registry.
-      - run: npx -y @siloy/hubspot-provisioning@0.1.1 validate
+      - run: npx -y @siloy/hubspot-provisioning@0.1.2 validate
         env:
           npm_config_registry: https://registry.npmjs.org
       - run: >-
-          npx -y @siloy/hubspot-provisioning@0.1.1 plan --mode preview
+          npx -y @siloy/hubspot-provisioning@0.1.2 plan --mode preview
           --comment-file plan-comment.md
           --sha "$HEAD_SHA" --ref "$HEAD_REF"
         env:
@@ -123,7 +125,8 @@ jobs:
           HEAD_REF: ${{ github.head_ref }}
           npm_config_registry: https://registry.npmjs.org
           PROVISIONING_URL: ${{ vars.PROVISIONING_URL }}
-          PROVISIONING_KEY: ${{ secrets.PROVISIONING_KEY }}
+          # The preview-only key: it cannot deploy.
+          PROVISIONING_KEY: ${{ secrets.PROVISIONING_PREVIEW_KEY }}
       # Runs also when the plan failed or was refused: the comment says why.
       - name: Post the plan on the pull request
         if: always() && hashFiles('plan-comment.md') != ''
@@ -153,7 +156,7 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: 24
-      - run: npx -y @siloy/hubspot-provisioning@0.1.1 deploy
+      - run: npx -y @siloy/hubspot-provisioning@0.1.2 deploy
         env:
           npm_config_registry: https://registry.npmjs.org
           PROVISIONING_URL: ${{ vars.PROVISIONING_URL }}
@@ -171,7 +174,10 @@ A deploy that would overwrite something someone changed by hand in HubSpot is re
 
 ### Trust boundary
 
-`PROVISIONING_KEY` is like any GitHub secret: anyone who can push a branch to the integration repo can change the workflow on that branch and use the key. Keep write access to the integration repo to trusted developers. A key can deploy as well as preview, so a preview job's key could also deploy to its portal; a preview-only key is planned.
+A key in a GitHub secret is like any GitHub secret: anyone who can push a branch to the integration repo can change the workflow on that branch and use it. Give the pull-request job a preview-only key, so the secret that job needs cannot deploy. That alone does not keep the deploy key in `main`'s job:
+
+- Where your GitHub plan has environments (public repos, or GitHub Pro, Team or Enterprise for private repos), store `PROVISIONING_KEY` as a secret of an environment whose deployment branches are limited to `main`, and give the deploy job `environment:` with that name. A workflow on another branch then cannot read it.
+- Without environments (GitHub Free with a private repo), every repository secret is readable by a workflow on any branch, the deploy key included. Keep write access to the integration repo to trusted developers.
 
 ## Editor support
 
@@ -195,7 +201,7 @@ The schema is also available as `@siloy/hubspot-provisioning/schema.json`. It de
 
 ## Upgrading
 
-When the blueprint rules change, the server may refuse older CLIs with `cli_outdated`. Upgrade with `npm install --save-dev @siloy/hubspot-provisioning@latest`, or raise the version in your workflow's `npx -y @siloy/hubspot-provisioning@0.1.1`.
+When the blueprint rules change, the server may refuse older CLIs with `cli_outdated`. Upgrade with `npm install --save-dev @siloy/hubspot-provisioning@latest`, or raise the version in your workflow's `npx -y @siloy/hubspot-provisioning@0.1.2`.
 
 When a command fails after the server created a run, it prints `Plan run:` and `Apply run:` ids; look them up in the provisioning app. After a timeout or error while waiting for an apply, the apply may still be running: check it before re-running.
 

package/dist/provisioning/src/api/types.d.ts

@@ -6,7 +6,7 @@
  * An error, refusal or run error code. The listed ones are those docs/ci-api.md documents, plus the client's own
  * `network`, `http_error` and `unexpected_response`; the server may add codes, so any string is accepted.
  */
-export type KnownErrorCode = 'invalid' | 'cli_outdated' | 'unauthenticated' | 'forbidden' | 'deploy_key_expired' | 'not_found' | 'preview_plan' | 'plan_unclassified' | 'blocking_updates' | 'mapping_target_missing' | 'nothing_to_apply' | 'reconnect_required' | 'apply_locked' | 'missing_scopes' | 'conflict' | 'too_large' | 'rate_limited' | 'internal' | 'environment' | 'hubspot' | 'plan_changed' | 'apply_failed' | 'deploy_key_revoked' | 'portal_moved' | 'dispatch_failed' | 'timed_out' | 'stopped' | 'never_started' | 'input' | 'network' | 'http_error' | 'unexpected_response' | (string & {});
+export type KnownErrorCode = 'invalid' | 'cli_outdated' | 'unauthenticated' | 'forbidden' | 'deploy_key_expired' | 'preview_only_key' | 'not_found' | 'preview_plan' | 'plan_unclassified' | 'blocking_updates' | 'mapping_target_missing' | 'nothing_to_apply' | 'reconnect_required' | 'apply_locked' | 'missing_scopes' | 'conflict' | 'too_large' | 'rate_limited' | 'internal' | 'environment' | 'hubspot' | 'plan_changed' | 'apply_failed' | 'deploy_key_revoked' | 'portal_moved' | 'dispatch_failed' | 'timed_out' | 'stopped' | 'never_started' | 'input' | 'network' | 'http_error' | 'unexpected_response' | (string & {});
 export type CiMode = 'preview' | 'deploy';
 export type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed';
 export interface CreatePlanRequest {
@@ -65,6 +65,7 @@ export interface CiRunView {
         blueprint: unknown;
         portal: unknown;
         remediation: string;
+        option?: 'allowRetype' | 'pruneOptions';
     }[];
     warnings: string[];
     blocking: BlockingUpdate[];
@@ -75,11 +76,15 @@ export interface CiRunView {
         property: string | null;
     }[];
     baselineInvalid: boolean;
+    /** A preview-only key's blueprint and portal have no live deploy key, or several; absent from older servers. */
+    deployKeyGap?: 'no_deploy_key' | 'several_deploy_keys' | null;
     appliable: boolean;
     refusal: {
         code: KnownErrorCode;
         message: string;
     } | null;
+    /** How to finish conflicts only allowRetype or pruneOptions resolves, which CI never sets; absent from older servers. */
+    finish?: string | null;
     applyRunId: string | null;
     error: {
         code: KnownErrorCode;

package/dist/provisioning/src/cli/hints.js

@@ -4,6 +4,7 @@ const HINTS = {
     deploy_key_expired: 'Ask a workspace owner to reactivate the key on the blueprint page, then re-run this job. The secret stays the same.',
     unauthenticated: 'The key is not valid (unknown, revoked or mistyped). Ask a workspace owner for a new key or a one-time link, and update the PROVISIONING_KEY secret.',
     forbidden: "The key's portal is no longer in the workspace.",
+    preview_only_key: 'Check which secret this job uses: the pull-request job gets the preview-only key, the job on the main branch a key that can deploy.',
     deploy_key_revoked: 'The key was revoked; an apply may already have changed the portal. Plan again with a new key.',
     reconnect_required: RECONNECT,
     missing_scopes: RECONNECT,

package/dist/provisioning/src/cli/render.js

@@ -3,13 +3,17 @@ import { hintFor } from './hints.js';
 export const COMMENT_MARKER = '<!-- hubspot-provisioning -->';
 const MAX_COMMENT_ISSUES = 10;
 const BASELINE_INVALID = "This key's last deploy no longer passes today's blueprint rules, so every update blocks until a deploy with nothing to apply.";
+const DEPLOY_KEY_GAP = {
+    no_deploy_key: 'This preview-only key compares with what the deploy key last deployed, but this blueprint and portal have no deploy key, so every update blocks. Create one for the job on the main branch.',
+    several_deploy_keys: 'This preview-only key compares with what the deploy key last deployed, but this blueprint and portal have several, and which one deploys is unknown, so every update blocks. Revoke the ones no job uses.',
+};
 const ACTIONS = {
     plan_again: 'plan again: re-run this job',
     reconnect: 'a person reconnects the portal in the provisioning app',
 };
 const REASONS = {
     changed_in_hubspot: 'changed in HubSpot since the last deploy',
-    no_baseline: 'no earlier deploy by this key to compare with',
+    no_baseline: 'no earlier deploy to compare with',
 };
 /** The console lines for a finished run (#105). Server text is printed as is. */
 export function renderRunText(run) {
@@ -18,11 +22,15 @@ export function renderRunText(run) {
         lines.push(`Changes: ${counts(run.summary) || 'none'}`);
     section(lines, 'Actions:', run.actions.map((a) => `${a.type} ${a.target}: ${a.summary}`));
     section(lines, 'Conflicts:', run.conflicts.map((c) => `${c.target} ${c.field}: ${c.remediation}`));
+    if (run.finish)
+        lines.push(`To finish: ${run.finish}`);
     section(lines, 'Blocking updates (hand edits in HubSpot the apply would overwrite):', run.blocking.map(blockingText));
     section(lines, 'Missing mapping targets (in neither the blueprint nor HubSpot):', run.missingTargets.map(targetName));
     section(lines, 'Warnings:', run.warnings);
     if (run.baselineInvalid)
         lines.push(BASELINE_INVALID);
+    if (run.deployKeyGap)
+        lines.push(DEPLOY_KEY_GAP[run.deployKeyGap]);
     if (run.refusal) {
         lines.push(run.refusal.message);
         pushHint(lines, run.refusal.code);
@@ -47,11 +55,15 @@ export function renderComment(run, context) {
     parts.push(about, '', run.summary ? `**Summary:** ${md(counts(run.summary)) || 'no changes.'}` : '**Summary:** unknown, the plan did not finish.', '');
     mdSection(parts, 'Changes', run.actions.map((a) => `**${md(a.type)}** ${md(a.target)}: ${md(a.summary)}`));
     mdSection(parts, 'Conflicts', run.conflicts.map((c) => `${md(c.target)} ${md(c.field)}: ${md(c.remediation)}`));
+    if (run.finish)
+        parts.push(`**To finish:** ${md(run.finish)}`, '');
     mdSection(parts, 'Blocking updates (hand edits in HubSpot)', run.blocking.map((b) => md(blockingText(b))));
     mdSection(parts, 'Missing mapping targets', run.missingTargets.map((t) => md(targetName(t))));
     mdSection(parts, 'Warnings', run.warnings.map(md));
     if (run.baselineInvalid)
         parts.push(md(BASELINE_INVALID), '');
+    if (run.deployKeyGap)
+        parts.push(md(DEPLOY_KEY_GAP[run.deployKeyGap]), '');
     parts.push(verdict(run));
     return `${parts.join('\n')}\n`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siloy/hubspot-provisioning",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Validate HubSpot provisioning blueprints offline and deploy them from CI.",
   "type": "module",
   "engines": { "node": ">=20" },