@siloy/hubspot-provisioning 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,373 @@
+import { parseArgs } from 'node:util';
+import { CiApiError, CiClient, CiTimeoutError } from '../api/client.js';
+import { commitInfo } from '../api/commit.js';
+import { MAX_BLUEPRINT_BYTES } from '../limits.js';
+import { checkMappingTargets, mappingTargetsSchema } from '../targets.js';
+import { validateBlueprintText } from '../validate.js';
+import { CLI_VERSION } from '../version.js';
+import { hintFor } from './hints.js';
+import { blockedReason, renderComment, renderFailureComment, renderRunText } from './render.js';
+const DEFAULT_TIMEOUT_MINUTES = 15;
+const MAX_TIMEOUT_MINUTES = 360;
+const APPLY_MAY_RUN = 'The apply may still be running; check the run in the provisioning app before re-running.';
+const USAGE = `Usage: hubspot-provisioning <command> [options]
+
+Commands:
+  validate [file] [--targets <json>]
+      Check the blueprint (default blueprint.yaml) offline.
+  plan [file] --mode preview|deploy [--targets <json>] [--comment-file <path>]
+       [--sha <sha>] [--ref <ref>] [--ci-run-url <url>] [--timeout <minutes>]
+      Plan the blueprint on the key's portal and print the result.
+  apply --plan-run <runId> [--timeout <minutes>]
+      Apply a deploy plan made by the same key.
+  deploy [file] [plan options except --mode]
+      Plan in deploy mode, then apply when there is something to apply.
+
+Options:
+  --targets <json>      Mapping targets: [{ "objectType": "contacts", "properties": ["..."] }]
+  --comment-file <path> Write the plan as a Markdown PR comment.
+  --timeout <minutes>   Give up after this long (default ${DEFAULT_TIMEOUT_MINUTES}, at most ${MAX_TIMEOUT_MINUTES}).
+  --help, --version
+
+Environment: PROVISIONING_URL and PROVISIONING_KEY (plan, apply, deploy).
+Exit codes: 0 success, 1 the blueprint, plan or apply failed, 2 usage or configuration error.`;
+/** Exit 2: a usage or configuration error. */
+class UsageError extends Error {
+}
+/** Exit 1, after the lines were printed. `message` and `issues` go in the failure comment. */
+class Failed extends Error {
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.issues = issues;
+    }
+}
+const PLAN_OPTIONS = {
+    targets: { type: 'string' },
+    'comment-file': { type: 'string' },
+    sha: { type: 'string' },
+    ref: { type: 'string' },
+    'ci-run-url': { type: 'string' },
+    timeout: { type: 'string' },
+};
+/** Runs one CLI command (#105). Returns the exit code (0, 1 or 2). */
+export async function runCli(argv, io) {
+    // Belt and braces: server text is scrubbed when it comes in (withServer); this catches whatever else carries the key.
+    const key = io.env.PROVISIONING_KEY?.trim() ?? '';
+    const safe = { ...io, out: (line) => io.out(scrubbed(line, key)), err: (line) => io.err(scrubbed(line, key)) };
+    const [command, ...rest] = argv;
+    try {
+        if (command === '--version' || command === '-v') {
+            safe.out(CLI_VERSION);
+            return 0;
+        }
+        if (command === '--help' || command === '-h' || (isCommand(command) && (rest.includes('--help') || rest.includes('-h')))) {
+            safe.out(USAGE);
+            return 0;
+        }
+        switch (command) {
+            case 'validate': return await validate(rest, safe);
+            case 'plan': return await plan(rest, safe, null);
+            case 'deploy': return await plan(rest, safe, 'deploy');
+            case 'apply': return await apply(rest, safe);
+            default:
+                safe.err(command === undefined ? 'No command given.' : `Unknown command: ${command}`);
+                safe.err(USAGE);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            safe.err(error.message);
+            safe.err('Run hubspot-provisioning --help for usage.');
+            return 2;
+        }
+        if (error instanceof Failed)
+            return 1;
+        throw error;
+    }
+}
+const isCommand = (name) => name === 'validate' || name === 'plan' || name === 'deploy' || name === 'apply';
+async function validate(argv, io) {
+    const { values, positionals } = parse(argv, { targets: { type: 'string' } }, 1);
+    const targets = values.targets === undefined ? null : await readTargets(values.targets, io);
+    const file = positionals[0] ?? 'blueprint.yaml';
+    const blueprint = await readBlueprint(file, io);
+    io.out('Blueprint is valid.');
+    if (targets) {
+        const { assumed } = checkMappingTargets(blueprint, targets);
+        if (assumed.length > 0)
+            io.out(`Assumed to exist in HubSpot: ${assumed.map((t) => (t.property === null ? t.objectType : `${t.objectType}.${t.property}`)).join(', ')}`);
+    }
+    return 0;
+}
+/**
+ * `plan`, or `deploy` when `forced` is 'deploy'. Once the arguments parse, every failure writes a failure comment
+ * (with --comment-file), unless the plan's own comment was written already; the exit code stays the failure's. A
+ * deploy whose apply fails or times out replaces the plan's comment ("Ready to deploy.") with the failure comment.
+ */
+async function plan(argv, io, forced) {
+    const options = forced ? PLAN_OPTIONS : { ...PLAN_OPTIONS, mode: { type: 'string' } };
+    const { values, positionals } = parse(argv, options, 1);
+    const given = forced ?? values.mode;
+    const key = io.env.PROVISIONING_KEY?.trim() ?? '';
+    const commentFile = values['comment-file'];
+    let commented = false;
+    /** Set once the deploy's apply starts: from then on a failure comment replaces the plan's. */
+    let applying = false;
+    const comment = async (render) => {
+        if (commentFile === undefined || (commented && !applying))
+            return;
+        commented = true;
+        await writeComment(commentFile, render(), io);
+    };
+    const onFailure = (message, hint, extra = {}) => comment(() => renderFailureComment(given === 'preview' || given === 'deploy' ? given : null, scrubbed(message, key), hint, { issues: scrubbed(extra.issues ?? [], key), runs: extra.runs ?? {} }));
+    try {
+        return await planSteps(values, positionals, io, forced, comment, onFailure, () => { applying = true; });
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            await onFailure(error.message, null);
+        else if (error instanceof Failed)
+            await onFailure(error.message, null, { issues: error.issues });
+        else
+            await onFailure(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, null);
+        throw error;
+    }
+}
+async function planSteps(values, positionals, io, forced, comment, onFailure, startApplying) {
+    const mode = forced ?? modeOf(values.mode);
+    const minutes = timeoutOf(values.timeout);
+    const env = environment(io);
+    const targets = values.targets === undefined ? [] : await readTargets(values.targets, io);
+    const commit = commitInfo(io.env, { sha: values.sha, ref: values.ref, ciRunUrl: values['ci-run-url'] });
+    if ('error' in commit)
+        throw new UsageError(commit.error);
+    const file = positionals[0] ?? 'blueprint.yaml';
+    const yaml = await readText(file, io);
+    await readBlueprint(file, io, yaml);
+    const ids = {};
+    return withServer(io, minutes, ids, env, onFailure, async (client, remaining) => {
+        const created = await client.createPlan({ yaml, mode, commit, mappingTargets: targets });
+        ids.plan = created.runId;
+        io.out(`Planning ${mode} of ${file}${created.version === null ? '' : ` as version ${created.version}`}: run ${created.runId}`);
+        const run = await client.waitForRun(created.runId, remaining());
+        io.out('');
+        for (const line of renderRunText(run))
+            io.out(line);
+        await comment(() => renderComment(run, { mode, version: created.version }));
+        // Also a deploy plan that is not appliable for no stated reason: blockedReason says so, renderRunText printed it.
+        if (blockedReason(run) !== null)
+            return 1;
+        if (forced === null || run.refusal?.code === 'nothing_to_apply') {
+            if (forced === null && mode === 'deploy' && run.appliable)
+                io.out(`Next: hubspot-provisioning apply --plan-run ${run.id}`);
+            return 0;
+        }
+        if (!run.appliable)
+            return 1;
+        startApplying();
+        return applyRun(client, run.id, io, ids, remaining, async (failed) => {
+            const message = `The apply failed: ${failed.error?.message ?? `the run ${failed.status === 'failed' ? 'failed' : 'did not finish'}.`}`;
+            await onFailure(message, failed.error ? hintFor(failed.error.code) : null, { runs: { ...ids } });
+        });
+    });
+}
+async function apply(argv, io) {
+    const { values } = parse(argv, { 'plan-run': { type: 'string' }, timeout: { type: 'string' } }, 0);
+    const planRun = values['plan-run'];
+    if (!planRun)
+        throw new UsageError('Give the plan run to apply: --plan-run <runId>.');
+    const minutes = timeoutOf(values.timeout);
+    const env = environment(io);
+    const ids = { plan: planRun };
+    return withServer(io, minutes, ids, env, async () => { }, (client, remaining) => applyRun(client, planRun, io, ids, remaining));
+}
+async function applyRun(client, planRunId, io, ids, remaining, onFailed) {
+    let runId;
+    try {
+        ({ runId } = await client.createApply(planRunId));
+    }
+    catch (error) {
+        if (error instanceof CiApiError && error.code === 'nothing_to_apply') {
+            io.out('Nothing to apply: the portal already matches this plan.');
+            return 0;
+        }
+        throw error;
+    }
+    ids.apply = runId;
+    io.out('');
+    io.out(`Applying plan ${planRunId}: run ${runId}`);
+    const run = await client.waitForRun(runId, remaining());
+    io.out('');
+    for (const line of renderRunText(run))
+        io.out(line);
+    if (run.status === 'succeeded')
+        return 0;
+    await onFailed?.(run);
+    return 1;
+}
+/**
+ * Creates the client with the command's deadline, scrubs the key from every run view it returns, and turns server
+ * refusals and timeouts into exit 1, after `onFailure` (the plan's failure comment).
+ */
+async function withServer(io, minutes, ids, env, onFailure, work) {
+    const deadline = new Date(Date.now() + minutes * 60_000);
+    const raw = (io.client ?? defaultClient)(env.url, env.key, { deadline });
+    const client = {
+        createPlan: (body) => raw.createPlan(body),
+        createApply: (planRunId) => raw.createApply(planRunId),
+        getRun: async (runId) => scrubbed(await raw.getRun(runId), env.key),
+        waitForRun: async (runId, timeoutMs) => scrubbed(await raw.waitForRun(runId, timeoutMs), env.key),
+    };
+    try {
+        return await work(client, () => Math.max(0, deadline.getTime() - Date.now()));
+    }
+    catch (error) {
+        if (error instanceof CiTimeoutError) {
+            const message = `Timed out after ${minutes} minute${minutes === 1 ? '' : 's'} waiting for the provisioning app.`;
+            io.err(message);
+            io.err(scrubbed(error.message, env.key));
+            printRunIds(io, ids);
+            await onFailure(message, null, { runs: { ...ids } });
+            return 1;
+        }
+        if (error instanceof CiApiError) {
+            const message = scrubbed(error.message, env.key);
+            const issues = issuesOf(scrubbed(error.details, env.key));
+            io.err(`Error (${error.code}): ${message}`);
+            for (const issue of issues)
+                io.err(`  - ${issue}`);
+            const hint = hintFor(error.code);
+            if (hint)
+                io.err(`Hint: ${hint}`);
+            printRunIds(io, ids);
+            await onFailure(message, hint, { issues, runs: { ...ids } });
+            return 1;
+        }
+        throw error;
+    }
+}
+/** The runs a failed command got to, so a person can look them up; an apply that was waited on may still be going. */
+function printRunIds(io, ids) {
+    if (ids.plan)
+        io.err(`Plan run: ${ids.plan}`);
+    if (ids.apply) {
+        io.err(`Apply run: ${ids.apply}`);
+        io.err(APPLY_MAY_RUN);
+    }
+}
+/** `value` with every occurrence of the key, in any string inside it, replaced by `[key]`. */
+function scrubbed(value, key) {
+    if (!key)
+        return value;
+    if (typeof value === 'string')
+        return value.split(key).join('[key]');
+    if (Array.isArray(value))
+        return value.map((item) => scrubbed(item, key));
+    if (value !== null && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrubbed(v, key)]));
+    return value;
+}
+const defaultClient = (baseUrl, key, options) => new CiClient({ baseUrl, key, deadline: options.deadline });
+function issuesOf(details) {
+    const issues = details?.issues;
+    return Array.isArray(issues) ? issues.filter((i) => typeof i === 'string') : [];
+}
+function parse(argv, options, maxPositionals) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+    if (parsed.positionals.length > maxPositionals)
+        throw new UsageError(`Unexpected argument: ${parsed.positionals[maxPositionals]}`);
+    return parsed;
+}
+function modeOf(mode) {
+    if (mode === 'preview' || mode === 'deploy')
+        return mode;
+    throw new UsageError(mode === undefined ? 'Give the mode: --mode preview or --mode deploy.' : `Unknown mode: ${mode}. Use preview or deploy.`);
+}
+function timeoutOf(text) {
+    if (text === undefined)
+        return DEFAULT_TIMEOUT_MINUTES;
+    const minutes = Number(text);
+    if (text.trim() === '' || !Number.isFinite(minutes) || minutes <= 0 || minutes > MAX_TIMEOUT_MINUTES) {
+        throw new UsageError(`--timeout takes a number of minutes above 0 and at most ${MAX_TIMEOUT_MINUTES}, not "${text}".`);
+    }
+    return minutes;
+}
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+function environment(io) {
+    const url = io.env.PROVISIONING_URL?.trim();
+    if (!url)
+        throw new UsageError('PROVISIONING_URL is not set: give the provisioning app URL, for example https://provisioning.example.com.');
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new UsageError('PROVISIONING_URL is not a valid URL.');
+    }
+    // The key goes along as a bearer token: never in clear text, except to this machine.
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && LOCAL_HOSTS.has(parsed.hostname))) {
+        throw new UsageError('PROVISIONING_URL must start with https://. Plain http:// is allowed only for localhost, 127.0.0.1 and [::1].');
+    }
+    const key = io.env.PROVISIONING_KEY?.trim();
+    if (!key)
+        throw new UsageError('PROVISIONING_KEY is not set: give the deploy key secret (hspk_...) from the repo\'s CI secrets.');
+    return { url, key };
+}
+async function readText(file, io) {
+    try {
+        return await io.readFile(file);
+    }
+    catch (error) {
+        throw new UsageError(`Could not read ${file}: ${error.message}`);
+    }
+}
+async function readTargets(file, io) {
+    const text = await readText(file, io);
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        throw new UsageError(`The targets file ${file} is not valid JSON: ${error.message}`);
+    }
+    const result = mappingTargetsSchema.safeParse(json);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.length > 0 ? `${i.path.join('.')}: ` : ''}${i.message}`);
+        throw new UsageError(`The targets file ${file} is not valid: ${issues.join('; ')}`);
+    }
+    return result.data;
+}
+/** Reads (unless given) and validates the blueprint; prints the issues and fails (exit 1) when it is too large or invalid. */
+async function readBlueprint(file, io, text) {
+    const yaml = text ?? await readText(file, io);
+    if (Buffer.byteLength(yaml, 'utf8') > MAX_BLUEPRINT_BYTES) {
+        const message = 'The blueprint is larger than 5 MiB; the server refuses it.';
+        io.err(message);
+        throw new Failed(message);
+    }
+    const result = validateBlueprintText(yaml);
+    if (!result.ok) {
+        io.err(`${file} is not a valid blueprint:`);
+        for (const issue of result.issues)
+            io.err(`  - ${issue}`);
+        throw new Failed(`${file} is not a valid blueprint.`, result.issues);
+    }
+    return result.blueprint;
+}
+/** Writes the comment; a failure is printed and otherwise ignored, so the command keeps its own exit code. */
+async function writeComment(path, text, io) {
+    try {
+        await io.writeFile(path, text);
+    }
+    catch (error) {
+        io.err(`Could not write the comment file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/provisioning/src/cli/hints.d.ts

@@ -0,0 +1,4 @@
+/** The codes with a hint; apps/web/test/server/ci/ci-contract.test.ts checks the server can send each (except the client's own). */
+export declare const HINTED_CODES: readonly string[];
+/** What to do about an error or refusal code, added after the server's message (#105). Null when the message says it all. */
+export declare function hintFor(code: string): string | null;

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

@@ -0,0 +1,21 @@
+const RECONNECT = 'A person must reconnect the portal in the provisioning app, then re-run this job.';
+const REACH = 'Check PROVISIONING_URL and that the provisioning app is reachable.';
+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.",
+    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,
+    cli_outdated: 'Upgrade: npm install --save-dev @siloy/hubspot-provisioning@latest, or raise the version your workflow runs with npx.',
+    rate_limited: "The key's rate limit is used up; wait 15 minutes.",
+    network: REACH,
+    http_error: REACH,
+    unexpected_response: 'The answer did not match this CLI. Upgrade @siloy/hubspot-provisioning, and check that PROVISIONING_URL is the provisioning app itself, not a proxy or sign-in page.',
+};
+/** The codes with a hint; apps/web/test/server/ci/ci-contract.test.ts checks the server can send each (except the client's own). */
+export const HINTED_CODES = Object.keys(HINTS);
+/** What to do about an error or refusal code, added after the server's message (#105). Null when the message says it all. */
+export function hintFor(code) {
+    return Object.hasOwn(HINTS, code) ? HINTS[code] : null;
+}

package/dist/provisioning/src/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises';
+import { runCli } from './commands.js';
+let code;
+try {
+    code = await runCli(process.argv.slice(2), {
+        out: (line) => console.log(line),
+        err: (line) => console.error(line),
+        env: process.env,
+        readFile: (path) => readFile(path, 'utf8'),
+        writeFile: (path, text) => writeFile(path, text, 'utf8'),
+    });
+}
+catch (error) {
+    // A bug, not a refusal: print only the message, never the object (it may hold a request, and with it the key).
+    const key = process.env.PROVISIONING_KEY?.trim();
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Unexpected error: ${key ? message.split(key).join('[key]') : message}`);
+    code = 1;
+}
+// Piped stdout/stderr are asynchronous on macOS: flush them before exiting.
+await new Promise((resolve) => process.stdout.write('', () => resolve()));
+await new Promise((resolve) => process.stderr.write('', () => resolve()));
+process.exit(code);

package/dist/provisioning/src/cli/render.d.ts

@@ -0,0 +1,25 @@
+import type { CiMode, CiRunView } from '../api/types.ts';
+/** First line of every PR comment, so a workflow can find and update its own comment. */
+export declare const COMMENT_MARKER = "<!-- hubspot-provisioning -->";
+/** The plan and apply runs a command created, as far as it got. */
+export interface RunIds {
+    plan?: string;
+    apply?: string;
+}
+/** The console lines for a finished run (#105). Server text is printed as is. */
+export declare function renderRunText(run: CiRunView): string[];
+/** The Markdown PR comment for a finished plan (#105). All server text goes in escaped. */
+export declare function renderComment(run: CiRunView, context: {
+    mode: CiMode;
+    version: number | null;
+}): string;
+/**
+ * The PR comment when no finished plan came back: the blueprint failed offline, the configuration is wrong, the server
+ * refused, or the time ran out. `mode` is null when it was not given or not valid. At most 10 issues are listed.
+ */
+export declare function renderFailureComment(mode: CiMode | null, message: string, hint: string | null, extra?: {
+    issues?: string[];
+    runs?: RunIds;
+}): string;
+/** Why a finished plan cannot be deployed, or null. Mirrors the plan command's exit 1. */
+export declare function blockedReason(run: CiRunView): string | null;

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

@@ -0,0 +1,149 @@
+import { hintFor } from './hints.js';
+/** First line of every PR comment, so a workflow can find and update its own comment. */
+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 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',
+};
+/** The console lines for a finished run (#105). Server text is printed as is. */
+export function renderRunText(run) {
+    const lines = [`${title(run)}: ${run.status}`];
+    if (run.summary)
+        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}`));
+    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.refusal) {
+        lines.push(run.refusal.message);
+        pushHint(lines, run.refusal.code);
+    }
+    const unexplained = unexplainedReason(run);
+    if (unexplained)
+        lines.push(unexplained);
+    if (run.error) {
+        lines.push(`Error (${run.error.code}): ${run.error.message}`);
+        if (run.error.action)
+            lines.push(`Action: ${run.error.action} (${ACTIONS[run.error.action] ?? run.error.action})`);
+        if (run.error.runId)
+            lines.push(`Other run: ${run.error.runId}`);
+        pushHint(lines, run.error.code);
+    }
+    return lines;
+}
+/** The Markdown PR comment for a finished plan (#105). All server text goes in escaped. */
+export function renderComment(run, context) {
+    const parts = [COMMENT_MARKER, `### Provisioning ${context.mode} plan`, ''];
+    const about = context.version === null ? `Run ${md(run.id)}.` : `Blueprint version ${context.version}, run ${md(run.id)}.`;
+    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)}`));
+    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), '');
+    parts.push(verdict(run));
+    return `${parts.join('\n')}\n`;
+}
+/**
+ * The PR comment when no finished plan came back: the blueprint failed offline, the configuration is wrong, the server
+ * refused, or the time ran out. `mode` is null when it was not given or not valid. At most 10 issues are listed.
+ */
+export function renderFailureComment(mode, message, hint, extra = {}) {
+    const parts = [COMMENT_MARKER, `### Provisioning ${mode === null ? '' : `${mode} `}plan`, '', `**Not deployable:** ${md(message)}`];
+    const issues = extra.issues ?? [];
+    if (issues.length > 0) {
+        parts.push('', ...issues.slice(0, MAX_COMMENT_ISSUES).map((issue) => `- ${md(issue)}`));
+        if (issues.length > MAX_COMMENT_ISSUES)
+            parts.push(`- …and ${issues.length - MAX_COMMENT_ISSUES} more`);
+    }
+    if (hint)
+        parts.push('', `Hint: ${md(hint)}`);
+    const runs = extra.runs ?? {};
+    if (runs.plan || runs.apply) {
+        parts.push('');
+        if (runs.plan)
+            parts.push(`Plan run: ${md(runs.plan)}`);
+        if (runs.apply)
+            parts.push(`Apply run: ${md(runs.apply)}`, '', md('The apply may still be running; check the run in the provisioning app before re-running.'));
+    }
+    return `${parts.join('\n')}\n`;
+}
+/** The same rule as the plan command's exit code: blocked is exit 1, everything else exit 0. */
+function verdict(run) {
+    const reason = blockedReason(run);
+    if (reason !== null)
+        return `**Not deployable:** ${md(reason)}`;
+    if (run.refusal?.code === 'nothing_to_apply')
+        return '**Nothing to change.**';
+    return '**Ready to deploy.**';
+}
+/** Why a finished plan cannot be deployed, or null. Mirrors the plan command's exit 1. */
+export function blockedReason(run) {
+    if (run.status !== 'succeeded')
+        return run.error?.message ?? `the run ${run.status === 'failed' ? 'failed' : 'did not finish'}.`;
+    if (run.refusal && run.refusal.code !== 'nothing_to_apply')
+        return run.refusal.message;
+    if (run.conflicts.length > 0)
+        return `${plural(run.conflicts.length, 'conflict')} with the portal.`;
+    if (run.blocking.length > 0)
+        return `${plural(run.blocking.length, 'update')} would overwrite hand edits in HubSpot.`;
+    if (run.missingTargets.length > 0)
+        return `${plural(run.missingTargets.length, 'mapping target')} in neither the blueprint nor HubSpot.`;
+    return unexplainedReason(run);
+}
+/** A succeeded deploy plan the server says cannot be applied, without saying why (no refusal): blocked all the same. */
+function unexplainedReason(run) {
+    if (run.kind !== 'plan' || run.mode !== 'deploy' || run.status !== 'succeeded' || run.appliable || run.refusal !== null)
+        return null;
+    if (run.conflicts.length > 0 || run.blocking.length > 0 || run.missingTargets.length > 0)
+        return null;
+    return `The plan cannot be applied, and the server gave no reason. Plan again; if it persists, report it with run ${run.id}.`;
+}
+function title(run) {
+    const name = run.kind === 'apply' ? 'Apply' : `${run.mode === 'deploy' ? 'Deploy' : 'Preview'} plan`;
+    return `${name} ${run.id}${run.version === null ? '' : ` (version ${run.version})`}`;
+}
+const counts = (summary) => Object.entries(summary).map(([key, n]) => `${n} ${key}`).join(', ');
+const targetName = (t) => (t.property === null ? t.objectType : `${t.objectType}.${t.property}`);
+const blockingText = (b) => `${b.target} ${b.field}: HubSpot has ${value(b.hubspot)}, the repo has ${value(b.repo)} (${REASONS[b.reason] ?? b.reason})`;
+function value(v) {
+    if (typeof v === 'string')
+        return `"${v}"`;
+    if (v === undefined || v === null)
+        return 'nothing';
+    return JSON.stringify(v);
+}
+const plural = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+function section(lines, heading, items) {
+    if (items.length === 0)
+        return;
+    lines.push(heading, ...items.map((item) => `  ${item}`));
+}
+function mdSection(parts, heading, items) {
+    if (items.length === 0)
+        return;
+    parts.push(`#### ${heading}`, '', ...items.map((item) => `- ${item}`), '');
+}
+function pushHint(lines, code) {
+    const hint = hintFor(code);
+    if (hint)
+        lines.push(`Hint: ${hint}`);
+}
+/**
+ * Server text as plain Markdown: on one line; every character that could format, link, embed HTML or start math
+ * escaped; and a zero-width non-joiner after each `@` and `#`, so GitHub makes no mention or issue reference of it.
+ */
+function md(text) {
+    return text.replace(/\s*[\r\n]+\s*/g, ' ').replace(/[\\`*_{}[\]()<>#+!|~&@$-]/g, '\\$&').replace(/[@#]/g, '$&\u200C');
+}

package/dist/provisioning/src/index.d.ts

@@ -0,0 +1,6 @@
+export { BLUEPRINT_FORMAT, type Blueprint } from '../../engine/src/blueprint/index.ts';
+export { validateBlueprintText, type ValidationResult } from './validate.ts';
+export { checkMappingTargets, mappingTargetsSchema, type AssumedTarget, type MappingTarget } from './targets.ts';
+export { CLI_VERSION } from './version.ts';
+export { CiApiError, CiClient, CiTimeoutError, type ClientOptions } from './api/client.ts';
+export type { ApiErrorBody, BlockingUpdate, ClassifiedUpdate, CiMode, CiRunView, CreateApplyResponse, CreatePlanRequest, CreatePlanResponse, KnownErrorCode, RunStatus, } from './api/types.ts';

package/dist/provisioning/src/index.js

@@ -0,0 +1,5 @@
+export { BLUEPRINT_FORMAT } from '../../engine/src/blueprint/index.js';
+export { validateBlueprintText } from './validate.js';
+export { checkMappingTargets, mappingTargetsSchema } from './targets.js';
+export { CLI_VERSION } from './version.js';
+export { CiApiError, CiClient, CiTimeoutError } from './api/client.js';

package/dist/provisioning/src/limits.d.ts

@@ -0,0 +1,2 @@
+/** The server refuses YAML over this many UTF-8 bytes (413): MAX_BLUEPRINT_BYTES in apps/web/src/server/blueprints/limits.ts. */
+export declare const MAX_BLUEPRINT_BYTES: number;

package/dist/provisioning/src/limits.js

@@ -0,0 +1,2 @@
+/** The server refuses YAML over this many UTF-8 bytes (413): MAX_BLUEPRINT_BYTES in apps/web/src/server/blueprints/limits.ts. */
+export const MAX_BLUEPRINT_BYTES = 5 * 1024 * 1024;

package/dist/provisioning/src/targets.d.ts

@@ -0,0 +1,16 @@
+import type { Blueprint, MappingTarget } from '../../engine/src/blueprint/index.ts';
+export { mappingTargetsSchema, type MappingTarget } from '../../engine/src/blueprint/index.ts';
+/** A mapping target the blueprint does not define, so it must already exist in HubSpot. */
+export interface AssumedTarget {
+    objectType: string;
+    /** `null`: the whole object is not in the blueprint. */
+    property: string | null;
+}
+/**
+ * The offline part of the mapping-target check (#105): which targets the blueprint defines, and which are assumed to
+ * exist in HubSpot. `assumed` is sorted by object type, then property, `null` first; a missing object is listed once.
+ */
+export declare function checkMappingTargets(blueprint: Blueprint, targets: MappingTarget[]): {
+    defined: MappingTarget[];
+    assumed: AssumedTarget[];
+};