@bridgeline-digital/hawk-app-cli 0.1.1 → 0.1.2-dev.20261027220454

package/README.md

@@ -233,14 +233,14 @@ npx hawk-app deploy --dry-run     # what hawk-app.json would change, without a v
 | `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, the app says what its page shows ("Explain this page"), and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
 | `deploy [<folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]` | Sends hawk-app.json first (its scopes and settings go with every deploy), then reserves the next version number, runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>` (when package.json has a `build` script, unless `--no-build`), then uploads every file in the build folder (the template's, `dist`, `out` or `public`, unless given) to `/<slug>/v<n>/` on the apps CDN, plus `queries/` and the bundled `functions` (if any) to the platform's private storage, and deploys the functions. Runs `npm audit` of the production dependencies first, asks before deploying with high or critical findings, and reports the counts to reviewers (see [Dependency check](#dependency-check); `--no-audit` skips it). Warns when the HTML loads absolute URLs outside `/<slug>/v<n>/`, which wouldn't load, and when the code calls a bridge feature whose scope `hawk-app.json` lacks (e.g. `app.ai.generate` without `ai:invoke`; `validate` and `doctor` check it too). Says whether the version is a draft (staff only until it's approved) or auto-approved, and when it cleared an approval request. `--alias staging` points the alias at the new version (see [Versions and aliases](#versions-and-aliases)). `--dry-run` only shows what hawk-app.json would change. |
 | `register` | Sends `hawk-app.json` without a new version (for scripts; `deploy` and `dev` already send it). It never releases anything and never changes the app's clients. On a released app, changes wait for review. |
-| `versions` | Every version with its status (draft, waiting, approved, rejected) and the aliases on it. |
+| `versions` | Every version with its status (draft, waiting, approved, rejected), the aliases on it, and where it was deployed from: git commit, branch, uncommitted changes, pipeline build and who (Bitbucket Pipelines' variables win over git). |
 | `alias set <name> <version>` / `alias delete <name>` | Point an alias at a version that isn't approved (only Bridgeline staff in its clients see it), or delete one of yours with no clients on it. Approvers do the rest. |
 | `open [--alias <name>]` | Opens the app's page in HawkSearch (dev or prod, from `--env`) to review it and submit it for approval; `--alias` shows it as that alias's clients see it. Prints the link when there's no browser. |
 | `docs [<topic>]` | Opens the developer docs at developers.hawksearchapps.com, or a topic's page (`start`, `versions`, `bridge`, `api`, `cli`, `commands`, `functions`, …; `hawk-app help docs` lists them). Prints the link when there's no browser. |
 | `doctor` | Checks everything a developer needs: Node, the login and platform, `hawk-app.json`, the project (bridge, build script), the template, the scopes the code uses, the app on the platform and the MCP config. Each line says what to fix; exits 1 when something must be. |
 | `help [<command> \| all]` | The commands by task; one command's details; or every detail. |
 | `why <client id>` | What a client's users see of the app, and why (the client list, its alias, that version's status). |
-| `status` | Shows the automated review checks approvers will see (bundle, dependencies, origins, queries, …), the released version, the newest version and its status, settings waiting for review, the approval request (waiting for approval, or rejected and why), auto-approve, review emails (when an approver turned them off), the view cache (when Engineering shortened or stopped it), visibility, scopes, system parameters, config keys and clients. |
+| `status` | Shows the automated review checks approvers will see (bundle, dependencies, origins, queries, …), the released version, the newest version and its status, where the last deploy came from (commit, branch, pipeline build), settings waiting for review, the approval request (waiting for approval, or rejected and why), auto-approve, review emails (when an approver turned them off), the view cache (when Engineering shortened or stopped it), visibility, scopes, system parameters, config keys and clients. |
 | `clients` / `clients add <id> [<id> …] [--name "<name>"] [--alias <name>]` / `clients exclude <id> [--name "<name>"]` / `clients remove <id>` | Which clients have the app, and which version (alias) each gets (see [Clients](#clients)). |
 | `data tables` / `data describe <table>` / `data run <file.sql> --client <id> [--param name=value …]` | The tables app queries can use, and running a query on dev (see [Custom data](#custom-data-queries)). |
 | `secrets list` / `secrets set <NAME> [--value-from-env VAR]` / `secrets delete <NAME>` | The app's function secrets (see [Functions](#functions)). |

package/agents/AGENTS.md

@@ -27,7 +27,9 @@ client at a time. It gets its context and all of its data through the bridge,
 - **Ask for the fewest scopes.** Each one is in `hawk-app.json` and reviewed; elevated scopes are never auto-approved.
 - **List outside origins.** `externalOrigins` in `hawk-app.json` should list every https origin the app loads from or
   calls (`[]` when none). The default `["*"]` fails review. To show images from hosts you can't list (a client's
-  product images), use `"img:*"`: images only, from any https origin, and it passes review.
+  product images), use `"img:*"`: images only, from any https origin, and it passes review. Add `"unsafe-eval"` only
+  when a library compiles code at run time (e.g. Rapid UI's Handlebars templates): the CSP blocks `eval`/`new Function`
+  otherwise, and review flags it.
 - **Handle a client without analytics.** When `app.context.tenant.analyticsProvisioned === false`, show a message
   instead of calling `app.analytics` or `app.data`.
 - Don't add a page heading: the host shows the app's name above the frame.

package/docs/bridge/README.md

@@ -357,7 +357,7 @@ only, `LandingPage` has no list), with HawkSearch's models: a misspelled field o
 `get(name)` of such a resource is typed too, and `HawkSearchModel<'Synonym'>` (or `'RedirectModel'`, `'LandingPage'`,
 …) names a model in your own code. The resources, as HawkSearch spells them: `banner`, `bannerzone`, `boostbury`,
 `campaign`, `Facet`, `Field`, `FieldInfo`, `LandingPage`, `landingPageLayout`, `paginationset`,
-`recommendationvisibility`, `redirect`, `sortingset`, `spellcheck`, `Synonym`, `visibility`, `visitortarget` (paths
+`recommendationvisibility`, `recommendationwidget`, `redirect`, `sortingset`, `spellcheck`, `Synonym`, `visibility`, `visitortarget` (paths
 ignore case). Other paths (`LandingPage/urls`, `reports/…`) stay on `get<T>(path)`. The types come from HawkSearch's dev
 API and are refreshed with each bridge release. To change data, see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite). For reporting, use
 analytics. Your assistant can look up any operation's fields, its bridge call and scope with the `hawk-apps` MCP
@@ -1744,7 +1744,8 @@ rejected, and why.
   (`fetch`, WebSockets) only the origins in `externalOrigins` (`"*"` allows any https origin, and fails the review
   check). List the origins it really uses: the apps CDN blocks everything else (a Content-Security-Policy), so a compromised npm dependency can't send
   data anywhere new. The platform API is always allowed. To show images from any site (for example a client's
-  product images) without opening anything else, use `"img:*"`. Dev mode on localhost has no such policy, so check a
+  product images) without opening anything else, use `"img:*"`. A library that compiles code at run time (Rapid UI's
+  Handlebars templates, `new Function`) needs `"unsafe-eval"`: no origin, and review flags it. Dev mode on localhost has no such policy, so check a
   deployed version in HawkSearch before it's released.
 - **Static files only.** Build to plain HTML, JS and CSS (`next build` with `output: 'export'`, `vite build`, …), with
   the base path read from `HAWK_APP_BASE_PATH` (`/<slug>/v<n>`, set by `hawk-app deploy`; the templates do this).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridgeline-digital/hawk-app-cli",
-  "version": "0.1.1",
+  "version": "0.1.2-dev.20261027220454",
   "description": "For Bridgeline developers: create, deploy and register Hawk Apps (Services-built tools embedded in HawkSearch). Requires a Hawk Apps publisher key.",
   "author": "Bridgeline Digital",
   "license": "UNLICENSED",

package/schema/hawk-app.schema.json

@@ -289,7 +289,7 @@
       ]
     },
     "externalOrigins": {
-      "description": "Outside origins the app may load scripts, styles, fonts and images from, embed, and call (fetch/XHR/WebSocket). [\"*\"] (the default when omitted) allows any https origin; a list allows only those; [] allows none. Entries starting with img: are for images only: \"img:*\" shows images from any https origin (e.g. a client's product images) and \"img:https://cdn.example.com\" from one, without allowing scripts, styles or calls there. Enforced by the apps CDN's Content-Security-Policy.",
+      "description": "Outside origins the app may load scripts, styles, fonts and images from, embed, and call (fetch/XHR/WebSocket). [\"*\"] (the default when omitted) allows any https origin; a list allows only those; [] allows none. Entries starting with img: are for images only: \"img:*\" shows images from any https origin (e.g. a client's product images) and \"img:https://cdn.example.com\" from one, without allowing scripts, styles or calls there. \"unsafe-eval\" is no origin: it lets the app's scripts compile code at run time, for libraries that need it (e.g. Rapid UI's Handlebars templates); review shows it. Enforced by the apps CDN's Content-Security-Policy.",
       "type": "array",
       "default": [
         "*"
@@ -302,6 +302,9 @@
           {
             "const": "*"
           },
+          {
+            "const": "unsafe-eval"
+          },
           {
             "pattern": "^(https|wss)://(\\*\\.)?([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)*[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(:[0-9]{1,5})?/?$"
           },

package/src/cli.mjs

@@ -10,6 +10,7 @@ import { upgrade, upgradeHint } from './upgrade.mjs';
 import { login, logout, whoami } from './login.mjs';
 import { sso } from './sso.mjs';
 import { checkNewSlug, confirmTakeover } from './slug-guard.mjs';
+import { describeSource, readSource } from './source.mjs';
 import { MANIFEST_FILE, loadManifest, newManifest, validateManifest } from './manifest.mjs';
 import { DEFAULT_ICON_SVG, checkIcon } from './app-icon.mjs';
 import { checkScreenshots } from './store-listing.mjs';
@@ -526,6 +527,7 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
                 client: client(),
                 alias,
                 manifest: settings,
+                source: readSource({ cwd: projectDir }),
                 registerSettings: async () => printRegisterBrief(await client().register(manifest.slug, settings, false), log),
                 beforeReserve: () => confirmTakeover({ client: client(), slug: manifest.slug, action: 'deploy', ...guard }),
                 confirmAudit: (report) => confirmVulnerabilities(report, guard),
@@ -580,6 +582,8 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
             log(`  released    ${app.status === 'Live' && app.liveVersion ? `v${app.liveVersion}  (default: every client without another alias)` : 'not yet  (only Bridgeline staff see it; an approver releases it)'}`);
             const newest = app.pendingVersion ?? (app.status !== 'Live' ? app.currentVersion : undefined);
             if (newest) log(`  newest      v${newest}  ${describeNewest(app)}`);
+            const last = app.lastChange;
+            if (last?.kind === 'deploy' && last.source) log(`  last deploy ${describeSource(last.source)} · ${last.name ?? 'unknown'}, ${last.at.slice(0, 10)}`);
             if (app.pending?.length) log(`  settings    waiting for review: ${app.pending.join(', ')}`);
             const review = describeReview(app);
             if (review) log(`  request     ${review}`);

package/src/deploy.mjs

@@ -6,6 +6,7 @@ import { buildFunction, describeConfig, describeFunctions, zipSources } from './
 import { checkAccessibility, describeAccessibility } from './accessibility.mjs';
 import { checkBuildUrls, describeBuildUrls } from './project-checks.mjs';
 import { askYesNo } from './slug-guard.mjs';
+import { describeSource } from './source.mjs';
 import { sourceMapIndex, splitSourceMaps } from './sourcemaps.mjs';
 
 const CONCURRENCY = 8;
@@ -43,8 +44,9 @@ export async function listFiles(dir) {
 /**
  * @param beforeReserve Runs after the local checks, just before a version number is taken (the slug check: slug-guard.mjs).
  * @param confirmAudit Called with the audit report when it has high or critical vulnerabilities; throws to stop the deploy.
+ * @param source Where it's deployed from (readSource in source.mjs), recorded on the version; null when unknown.
  */
-export async function deploy({ client, slug, dir, alias, manifest, registerSettings, iconFile = null, storeFiles = [], build = true, serverFiles = [], functions = [], projectDir = process.cwd(), audit = true, runBuild = npmRunBuild, runAudit = npmAudit, runAccessibility = checkAccessibility, beforeReserve, confirmAudit, fetchImpl = fetch, log = console.log }) {
+export async function deploy({ client, slug, dir, alias, manifest, source = null, registerSettings, iconFile = null, storeFiles = [], build = true, serverFiles = [], functions = [], projectDir = process.cwd(), audit = true, runBuild = npmRunBuild, runAudit = npmAudit, runAccessibility = checkAccessibility, beforeReserve, confirmAudit, fetchImpl = fetch, log = console.log }) {
     // Without a build step the folder must already be there: check before reserving a version.
     if (!build) await checkFolder(dir, false);
 
@@ -152,10 +154,11 @@ export async function deploy({ client, slug, dir, alias, manifest, registerSetti
         built.map((fn) => fn.name),
         report,
         accessibility,
-        alias ? { alias, manifest } : {},
+        { ...(alias ? { alias, manifest } : {}), ...(source ? { source } : {}) },
     );
     const n = completed.version ?? version;
     log(`✔ Deployed v${n} of ${slug} (${completed.files ?? files.length} files${queriesNote}).${describeState(completed)}`);
+    if (source) log(`  from ${describeSource(source)}`);
     if (completed.entryUrl) log(`  ${completed.entryUrl}`);
     if (built.length && completed.state === 'pending') log('  (Versions with functions always need review, even on auto-approve apps.)');
     if (completed.submissionCleared) log(`  ! ${submissionClearedMessage('version')}`);

package/src/manifest.mjs

@@ -369,7 +369,8 @@ export function validateManifest(manifest) {
         } else {
             const norm = (o) => o.trim().replace(/\/$/, '').toLowerCase();
             const isImage = (o) => norm(o).startsWith('img:');
-            const bad = origins.filter((o) => o !== '*' && !isImage(o) && !ORIGIN.test(norm(o)));
+            // "unsafe-eval" is no origin: it lets the app's scripts compile code at run time (Rapid UI's templates).
+            const bad = origins.filter((o) => o !== '*' && norm(o) !== 'unsafe-eval' && !isImage(o) && !ORIGIN.test(norm(o)));
             const badImages = origins.filter((o) => isImage(o) && norm(o) !== 'img:*' && !(norm(o).startsWith('img:https://') && ORIGIN.test(norm(o).slice(4))));
             if (badImages.length) {
                 errors.push(`externalOrigins: ${badImages.map((o) => `"${o}"`).join(', ')} must be image origins like img:https://cdn.example.com, or img:* for images from any https origin.`);

package/src/mcp-rules.mjs

@@ -17,7 +17,7 @@ export const FALLBACK = {
     version: 1,
     dashboard: {
         apiVersion: 'v11',
-        writeResources: ['banner', 'boostbury', 'campaign', 'visibility', 'visitortarget', 'redirect', 'synonym', 'spellcheck', 'paginationset', 'sortingset', 'recommendationvisibility', 'landingpagelayout', 'facet', 'landingpage'],
+        writeResources: ['banner', 'boostbury', 'campaign', 'visibility', 'visitortarget', 'redirect', 'synonym', 'spellcheck', 'paginationset', 'sortingset', 'recommendationvisibility', 'recommendationwidget', 'landingpagelayout', 'facet', 'landingpage'],
         maxBulkItems: 1000,
         maxWriteRequestBytes: 5 * 1024 * 1024,
         writesPerMinute: 120,

package/src/platform.mjs

@@ -71,12 +71,16 @@ export function platformClient({ url = process.env.HAWK_APPS_PLATFORM_URL, key =
         /** Creates or updates the function's Lambda from the uploaded bundle: { name, lambdaVersion, codeSha256 }. */
         deployFunction: (slug, version, name, config) =>
             call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/functions/${encodeURIComponent(name)}`, config),
-        /** `extra`: `{ alias, manifest }` for a deploy for an alias (the branch's hawk-app.json goes with it). */
+        /**
+         * `extra`: `{ alias, manifest }` for a deploy for an alias (the branch's hawk-app.json goes with it); `source`:
+         * where it was deployed from (source.mjs).
+         */
         completeVersion: (slug, version, files, serverFiles = [], functions = [], audit, accessibility, extra = {}) =>
             call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/complete`, {
                 files,
                 ...(extra.alias ? { alias: extra.alias } : {}),
                 ...(extra.manifest ? { manifest: extra.manifest } : {}),
+                ...(extra.source ? { source: extra.source } : {}),
                 ...(serverFiles.length ? { serverFiles } : {}),
                 ...(functions.length ? { functions } : {}),
                 ...(audit ? { audit } : {}),

package/src/slug-guard.mjs

@@ -4,6 +4,7 @@
 //   - register / deploy: when someone else's key made the app's last change, ask before going on (--yes skips it; a
 //     pipeline, with no terminal to ask in, gets a warning and goes on).
 import { createInterface } from 'node:readline';
+import { describeSource } from './source.mjs';
 
 /**
  * What the platform says about a slug for the caller's key: free (404), another publisher's (409 slug_owned), or this
@@ -23,7 +24,8 @@ export async function slugStatus(client, slug) {
 const describeChange = (last) => {
     const who = last.name || last.keyId || 'a shared key';
     const when = last.at ? new Date(last.at).toLocaleString() : 'earlier';
-    return `${last.kind === 'deploy' ? 'deployed' : 'registered'} by ${who} on ${when}`;
+    const from = describeSource(last.source);
+    return `${last.kind === 'deploy' ? 'deployed' : 'registered'} by ${who} on ${when}${from ? ` (${from})` : ''}`;
 };
 
 /** create / init: throws when the slug is taken; logs a note when it couldn't check. */

package/src/source.mjs

@@ -0,0 +1,43 @@
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Where a deploy comes from, sent with the version so teammates can tell versions apart (`hawk-app versions`, and the
+ * question before deploying over someone else's change): the git commit and branch, whether the app's folder has
+ * uncommitted changes, and the pipeline build. Bitbucket Pipelines' variables win over git (a pipeline checks out a
+ * commit, not a branch). Null outside a git repo and outside CI.
+ */
+export function readSource({ cwd = process.cwd(), env = process.env, run = git } = {}) {
+    const pipeline = env.BITBUCKET_BUILD_NUMBER ? 'bitbucket' : env.CI && env.CI !== 'false' ? 'ci' : null;
+    const commit = env.BITBUCKET_COMMIT || run(cwd, ['rev-parse', 'HEAD']);
+    if (!commit && !pipeline) return null;
+    const head = commit ? run(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']) : null;
+    const branch = env.BITBUCKET_BRANCH || (head && head !== 'HEAD' ? head : null);
+    // Only the app's own folder: in a monorepo, other apps' changes don't make this version differ from the commit.
+    const dirty = commit ? Boolean(run(cwd, ['status', '--porcelain', '--', '.'])) : false;
+    return {
+        ...(commit ? { commit } : {}),
+        ...(branch ? { branch } : {}),
+        ...(dirty ? { dirty } : {}),
+        ...(pipeline ? { pipeline } : {}),
+        ...(pipeline === 'bitbucket' ? { build: env.BITBUCKET_BUILD_NUMBER } : {}),
+    };
+}
+
+/** "a1b2c3d on dev + uncommitted changes, bitbucket #123"; '' when nothing was reported. */
+export function describeSource(source) {
+    if (!source) return '';
+    const parts = [];
+    if (source.commit) parts.push(source.commit.slice(0, 7));
+    if (source.branch) parts.push(`on ${source.branch}`);
+    let text = parts.join(' ');
+    if (source.dirty) text += ' + uncommitted changes';
+    if (source.pipeline) text += `${text ? ', ' : ''}${source.pipeline}${source.build ? ` #${source.build}` : ''}`;
+    return text;
+}
+
+/** A git command's trimmed output; null when git isn't there, this isn't a repo, or it printed nothing. */
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+    if (result.error || result.status !== 0) return null;
+    return result.stdout.trim() || null;
+}

package/src/versions.mjs

@@ -1,4 +1,5 @@
 import { DEFAULT_ALIAS, checkAlias } from './aliases.mjs';
+import { describeSource } from './source.mjs';
 
 /**
  * Versions, aliases and "why": the developer's view of who sees which version.
@@ -28,6 +29,8 @@ export async function versionsCommand({ client, manifest, log = console.log }) {
         const note = STATUS_NOTE[v.status] ? `  (${STATUS_NOTE[v.status]})` : '';
         const branch = v.deployedFor ? `  deployed for ${v.deployedFor}` : '';
         log(`  v${String(v.version).padEnd(4)} ${v.status.padEnd(9)}${aliases}${note}${branch}`);
+        const from = describeSource(v.source);
+        if (from) log(`         from ${from}${v.createdByName ? ` · ${v.createdByName}` : ''}`);
         if (v.status === 'rejected' && v.rejectedReason) log(`         rejected: ${v.rejectedReason}`);
     }
     log('Clients get the version of their alias (default without one); users see it only when it\'s approved.');