@stravica-ai/digital-operator-pa 0.1.32 → 0.1.33

package/dist/engineering-pa-cli/docs/gsc.md

@@ -52,34 +52,34 @@ Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
    single-file vault. Store the key in the pot the host is already
    configured to read; no `pa gsc`-specific configuration is needed.
 
-6. **Store Cloudflare credentials** (also one-time). Two key shapes are
-   supported; pick whichever fits your setup:
+6. **Store Cloudflare credentials** (also one-time). Each CF account is
+   addressed by a suffixed vault-key pair. `--account <name>` is required
+   on every invocation — the unsuffixed bare pair that used to be a
+   single-account default was dropped in the 2026-09-01 rename
+   (`w-2026-08-31-dave-010`).
 
-   **Single-account setup** — one CF account, no `--account` flag needed:
-   ```bash
-   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY <token>
-   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID <account-id>
-   ```
+   Pick the surface segment that matches how the token is actually
+   scoped in Cloudflare:
 
-   **Multi-account setup** — multiple CF accounts, each addressed by name:
    ```bash
-   # Stravica account → addressed as --account stravica
-   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY_STRAVICA <token>
-   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID_STRAVICA <account-id>
+   # Stravica account (Workers Scripts + D1) → --account stravica
+   pnpm exec secrets set CLOUDFLARE_WORKERS_API_TOKEN_STRAVICA <token>
+   pnpm exec secrets set CLOUDFLARE_WORKERS_ACCOUNT_ID_STRAVICA <account-id>
 
-   # Clive account → addressed as --account clive
-   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY_CLIVE <token>
+   # Clive account (Pages + zone purge) → --account clive
+   pnpm exec secrets set CLOUDFLARE_PAGES_API_TOKEN_CLIVE <token>
    pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID_CLIVE <account-id>
    ```
 
-   The CF API token needs `Zone:DNS:Edit` and `Zone:Zone:Read` for any
-   zones the tool will operate on. Account-level "Write to all resources"
-   tokens also work.
+   The CF API token needs the permissions its surface implies (for DNS
+   planting: `Zone:DNS:Edit` and `Zone:Zone:Read` on the target zones;
+   account-level "Write to all resources" tokens also work).
 
-   For back-compat, the legacy `CLOUDFLARE_API_TOKEN` /
-   `CLOUDFLARE_ACCOUNT_ID` pair is read as a last-resort fallback when
-   no `--account` flag is passed and the `CLOUDFLARE_PAGES_*` unsuffixed
-   pair is absent. Don't rely on it — set the `CLOUDFLARE_PAGES_*` keys.
+   For back-compat, the deprecated `CLOUDFLARE_PAGES_API_KEY_<NAME>` /
+   `CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>` pair is still accepted, and a
+   hit emits a stderr deprecation warning naming the current pair. Rename
+   the vault entries at your convenience — the deprecated pair will be
+   removed in a follow-up.
 
    Same scoped-vault note as the SA key: on scoped hosts these live in
    whichever pot `secrets get` reads (see step 5); use `secrets set --scope
@@ -134,26 +134,38 @@ pnpm exec pa gsc list-properties
 
 ## Multi-account selection
 
-When `--account <name>` is passed to `verify-via-cf-dns`, the tool resolves
-the Cloudflare credentials by upper-casing the name and looking up the
-corresponding suffixed vault pair. For example:
+`--account <name>` is required on every invocation. The tool upper-cases
+the name and tries the candidate vault-key pairs below in order — the
+first fully-present pair wins. Storing multiple pairs for the same
+account is a supported migration state; the tool always picks the
+highest-priority pair that resolves.
 
 ```
---account stravica  ->  CLOUDFLARE_PAGES_API_KEY_STRAVICA
-                        CLOUDFLARE_PAGES_ACCOUNT_ID_STRAVICA
---account clive     ->  CLOUDFLARE_PAGES_API_KEY_CLIVE
-                        CLOUDFLARE_PAGES_ACCOUNT_ID_CLIVE
+1.  CLOUDFLARE_WORKERS_API_TOKEN_<NAME>
+    CLOUDFLARE_WORKERS_ACCOUNT_ID_<NAME>
+    Workers surface — Workers Scripts, D1, KV. Used by --account stravica.
+
+2.  CLOUDFLARE_PAGES_API_TOKEN_<NAME>
+    CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+    Pages surface — Pages + zone purge. Used by --account clive.
+
+3.  CLOUDFLARE_PAGES_API_KEY_<NAME>
+    CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+    Deprecated pre-2026-09-01 naming. Accepted with a stderr warning;
+    will be removed in a follow-up. Rename the vault entries at your
+    convenience.
 ```
 
-If `--account` is passed but the suffixed pair isn't set, the command
-fails fast with a message telling you which key is missing. It does
-**not** silently fall back to the unsuffixed pair — that would defeat
-the safety the flag exists to provide.
+If `--account` is passed but none of the candidate pairs are fully set,
+the command fails fast with a message naming the primary (WORKERS) pair
+you're expected to store. It never silently falls back to any pair not
+addressed by the suffix — that would defeat the safety the flag exists
+to provide.
 
-Without `--account`, resolution order is:
-1. `CLOUDFLARE_PAGES_API_KEY` + `CLOUDFLARE_PAGES_ACCOUNT_ID`
-2. Legacy `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` (back-compat
-   only; do not rely on this).
+The unsuffixed bare pair (`CLOUDFLARE_PAGES_API_KEY` /
+`CLOUDFLARE_PAGES_ACCOUNT_ID`) and the very-legacy
+`CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` pair are no longer
+read — `--account <name>` is mandatory.
 
 The account name accepts letters and digits only — anything else is a
 usage error.

package/dist/engineering-pa-cli/docs/staging-alias.md

@@ -98,8 +98,11 @@ Edit `src/staging-alias/sites.mjs`. Add one entry:
 },
 ```
 
-…and store the vault keys: `CLOUDFLARE_PAGES_API_KEY_NEWSITE` +
-`CLOUDFLARE_PAGES_ACCOUNT_ID_NEWSITE`.
+…and store the vault keys under the surface segment that matches how
+the token is scoped: `CLOUDFLARE_WORKERS_API_TOKEN_NEWSITE` +
+`CLOUDFLARE_WORKERS_ACCOUNT_ID_NEWSITE` (Workers surface), or
+`CLOUDFLARE_PAGES_API_TOKEN_NEWSITE` + `CLOUDFLARE_PAGES_ACCOUNT_ID_NEWSITE`
+(Pages surface). See `packages/cli/docs/gsc.md` for the candidate order.
 
 ## Exit codes
 

package/dist/engineering-pa-cli/src/gsc/cli.mjs

@@ -53,14 +53,19 @@ Auth (one-time setup; see docs/gsc.md):
     GSC_SERVICE_ACCOUNT_KEY (entire JSON contents as the value).
   - SA email added as a user on each GSC property via the GSC dashboard.
 
-Cloudflare DNS planting reads two vault keys. Resolution order:
-  1. With --account <name>: CLOUDFLARE_PAGES_API_KEY_<NAME> +
-                            CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
-                            (e.g. --account stravica -> *_STRAVICA pair)
-  2. Without --account:     CLOUDFLARE_PAGES_API_KEY +
-                            CLOUDFLARE_PAGES_ACCOUNT_ID
-  3. Legacy fallback:       CLOUDFLARE_API_TOKEN +
-                            CLOUDFLARE_ACCOUNT_ID
+Cloudflare DNS planting reads two vault keys. --account <name> is
+required (letters/digits only). The suffix is upper-cased and each
+candidate pair below is tried in order — first fully-present pair wins.
+
+  1. CLOUDFLARE_WORKERS_API_TOKEN_<NAME> +
+     CLOUDFLARE_WORKERS_ACCOUNT_ID_<NAME>
+     (Workers surface — e.g. --account stravica)
+  2. CLOUDFLARE_PAGES_API_TOKEN_<NAME> +
+     CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+     (Pages surface — e.g. --account clive)
+  3. CLOUDFLARE_PAGES_API_KEY_<NAME> +
+     CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+     (deprecated pre-2026-09-01 naming; hit emits a stderr warning)
 `;
 
 export async function run(argv, overrides = {}) {

package/dist/engineering-pa-cli/src/gsc/cloudflare.mjs

@@ -5,22 +5,29 @@
 //   2. find an existing TXT record by name (idempotency)
 //   3. create or update a TXT record
 //
-// Credentials are read from the SOPS vault. The vault holds two key
-// shapes for Cloudflare:
+// Credentials are read from the SOPS vault. The vault holds account-suffixed
+// pairs — the caller picks the suffix via the `account` option (lower-cased
+// externally; matched case-insensitively to the upper-case suffix).
 //
-//   - Account-suffixed pair (preferred — multi-account safe):
-//       CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
-//       CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
-//     The caller picks the suffix via the `account` option (lower-cased
-//     externally; matched case-insensitively to the upper-case suffix).
+// Vault-key shapes tried in order per account (2026-09-01 rename,
+// w-2026-08-31-dave-010; see vault-key-rename-plan-2026-08-31.md):
 //
-//   - Unsuffixed pair (single-account default):
-//       CLOUDFLARE_PAGES_API_KEY
-//       CLOUDFLARE_PAGES_ACCOUNT_ID
+//   1. Workers surface (Workers Scripts / D1 / KV) — e.g. Stravica:
+//        CLOUDFLARE_WORKERS_API_TOKEN_<SUFFIX>
+//        CLOUDFLARE_WORKERS_ACCOUNT_ID_<SUFFIX>
 //
-//   - Legacy bare pair (back-compat fallback):
-//       CLOUDFLARE_API_TOKEN
-//       CLOUDFLARE_ACCOUNT_ID
+//   2. Pages surface (Pages + zone purge) — e.g. Clive:
+//        CLOUDFLARE_PAGES_API_TOKEN_<SUFFIX>
+//        CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
+//
+//   3. Deprecated (pre-2026-09-01) — accepted with a stderr warning during
+//      the transition window; will be removed in a follow-up:
+//        CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
+//        CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
+//
+// The unsuffixed bare pair (CLOUDFLARE_PAGES_API_KEY / CLOUDFLARE_PAGES_
+// ACCOUNT_ID) that used to be accepted as a single-account default was
+// removed in this same rename — `--account <name>` is now required.
 //
 // `fetchImpl` and `now` are injectable for tests.
 
@@ -28,18 +35,23 @@ import { resolveCommandPaths, checkVault, secretsFileExists, sopsDecrypt, VaultE
 
 const CF_API = 'https://api.cloudflare.com/client/v4';
 
-// Vault-key shapes. `*_TEMPLATE` uses `<S>` as the suffix placeholder.
-const VAULT_KEYS = Object.freeze({
-  // Account-suffixed (preferred).
-  tokenTemplate: 'CLOUDFLARE_PAGES_API_KEY_<S>',
-  accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
-  // Unsuffixed (single-account default).
-  tokenUnsuffixed: 'CLOUDFLARE_PAGES_API_KEY',
-  accountIdUnsuffixed: 'CLOUDFLARE_PAGES_ACCOUNT_ID',
-  // Legacy bare (back-compat fallback).
-  tokenLegacy: 'CLOUDFLARE_API_TOKEN',
-  accountIdLegacy: 'CLOUDFLARE_ACCOUNT_ID',
-});
+// Ordered candidate templates. First fully-present pair wins per account.
+// The `deprecated` flag drives the stderr warning + return-value flag.
+const CANDIDATE_TEMPLATES = Object.freeze([
+  Object.freeze({
+    tokenTemplate: 'CLOUDFLARE_WORKERS_API_TOKEN_<S>',
+    accountIdTemplate: 'CLOUDFLARE_WORKERS_ACCOUNT_ID_<S>',
+  }),
+  Object.freeze({
+    tokenTemplate: 'CLOUDFLARE_PAGES_API_TOKEN_<S>',
+    accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
+  }),
+  Object.freeze({
+    tokenTemplate: 'CLOUDFLARE_PAGES_API_KEY_<S>',
+    accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
+    deprecated: true,
+  }),
+]);
 
 /**
  * Normalise an `--account` value to the upper-case suffix used in the
@@ -65,28 +77,32 @@ export function accountSuffix(account) {
 }
 
 /**
- * Build the vault key names a given `account` selection resolves to.
- * If `account` is omitted, returns the unsuffixed pair (with a legacy
- * fallback list for back-compat).
+ * Build the ordered list of vault-key candidate pairs a given `account`
+ * selection resolves to. Callers try candidates in order — first fully-
+ * present pair wins.
  *
- * @param {string} [account]
- * @returns {{ tokenKey: string, accountIdKey: string, fallbacks?: Array<{tokenKey: string, accountIdKey: string}> }}
+ * @param {string} account   Required — the unsuffixed bare pair was dropped
+ *                           in the 2026-09-01 rename (w-2026-08-31-dave-010).
+ * @returns {{ candidates: Array<{tokenKey: string, accountIdKey: string, deprecated?: boolean}> }}
  */
 export function resolveVaultKeys(account) {
-  if (account) {
-    const s = accountSuffix(account);
-    return {
-      tokenKey: VAULT_KEYS.tokenTemplate.replace('<S>', s),
-      accountIdKey: VAULT_KEYS.accountIdTemplate.replace('<S>', s),
-    };
+  if (!account) {
+    throw new VaultError(
+      '--account <name> is required (e.g. --account stravica). ' +
+      'The unsuffixed vault-key fallback was removed in the 2026-09-01 rename.',
+      1,
+    );
   }
-  return {
-    tokenKey: VAULT_KEYS.tokenUnsuffixed,
-    accountIdKey: VAULT_KEYS.accountIdUnsuffixed,
-    fallbacks: [
-      { tokenKey: VAULT_KEYS.tokenLegacy, accountIdKey: VAULT_KEYS.accountIdLegacy },
-    ],
-  };
+  const s = accountSuffix(account);
+  const candidates = CANDIDATE_TEMPLATES.map((tpl) => {
+    const entry = {
+      tokenKey: tpl.tokenTemplate.replace('<S>', s),
+      accountIdKey: tpl.accountIdTemplate.replace('<S>', s),
+    };
+    if (tpl.deprecated) entry.deprecated = true;
+    return entry;
+  });
+  return { candidates };
 }
 
 /**
@@ -95,19 +111,18 @@ export function resolveVaultKeys(account) {
  *
  * Resolution order:
  *   1. Test overrides (`cloudflareToken` + `cloudflareAccountId`).
- *   2. If `account` provided: only the suffixed pair, hard-fail if missing.
- *   3. Otherwise: unsuffixed pair, then the legacy bare pair as fallback.
+ *   2. `--account` is required. Try each candidate pair in order; first
+ *      fully-present pair wins. A hit on a deprecated pair emits a
+ *      stderr warning (unless `warn` is overridden for tests).
  *
  * @param {object} overrides
  * @param {object} [overrides.paths]
  * @param {string} [overrides.cloudflareToken]
  * @param {string} [overrides.cloudflareAccountId]
- * @param {string} [overrides.account]            Account selector (e.g. "stravica").
+ * @param {string} [overrides.account]            Account selector (e.g. "stravica"). Required unless raw creds supplied.
  * @param {object} [overrides.vaultData]          Pre-decrypted vault map (test seam).
- *        When provided, the function uses this instead of running the SOPS
- *        check + decrypt. Lets tests cover the suffix-resolution and
- *        fallback paths without touching the filesystem.
- * @returns {Promise<{token: string, accountId: string, account: string|null, vaultKeys: {tokenKey: string, accountIdKey: string}}>}
+ * @param {Function} [overrides.warn]             Test seam for the deprecation warning (defaults to writing to stderr).
+ * @returns {Promise<{token: string, accountId: string, account: string|null, vaultKeys: {tokenKey: string, accountIdKey: string, deprecated?: boolean}}>}
  */
 export async function loadCloudflareCreds(overrides = {}) {
   if (overrides.cloudflareToken && overrides.cloudflareAccountId) {
@@ -118,6 +133,9 @@ export async function loadCloudflareCreds(overrides = {}) {
       vaultKeys: null,
     };
   }
+
+  const plan = resolveVaultKeys(overrides.account);
+
   let data;
   if (overrides.vaultData) {
     data = overrides.vaultData;
@@ -143,50 +161,33 @@ export async function loadCloudflareCreds(overrides = {}) {
     data = await sopsDecrypt(paths, paths.secretsFile);
   }
 
-  const plan = resolveVaultKeys(overrides.account);
+  const warn = overrides.warn || ((msg) => process.stderr.write(`${msg}\n`));
 
-  // Account-suffixed: must hit exactly the suffixed pair.
-  if (overrides.account) {
-    const token = data[plan.tokenKey];
-    const accountId = data[plan.accountIdKey];
-    if (!token || !accountId) {
-      const missing = [];
-      if (!token) missing.push(plan.tokenKey);
-      if (!accountId) missing.push(plan.accountIdKey);
-      throw new VaultError(
-        `--account "${overrides.account}" expects vault keys [${missing.join(', ')}] but they are not set. ` +
-        `Store them with:\n  secrets set ${plan.tokenKey} <token>\n  secrets set ${plan.accountIdKey} <id>`,
-        1,
-      );
-    }
-    return {
-      token,
-      accountId,
-      account: overrides.account,
-      vaultKeys: { tokenKey: plan.tokenKey, accountIdKey: plan.accountIdKey },
-    };
-  }
-
-  // No --account: try unsuffixed pair first, then legacy bare pair.
-  const candidates = [
-    { tokenKey: plan.tokenKey, accountIdKey: plan.accountIdKey },
-    ...(plan.fallbacks || []),
-  ];
-  for (const cand of candidates) {
+  for (const cand of plan.candidates) {
     const token = data[cand.tokenKey];
     const accountId = data[cand.accountIdKey];
     if (token && accountId) {
-      return { token, accountId, account: null, vaultKeys: cand };
+      if (cand.deprecated) {
+        warn(
+          `warning: Cloudflare vault keys [${cand.tokenKey}, ${cand.accountIdKey}] are deprecated ` +
+          `(pre-2026-09-01 naming). Rename to the current pair — see ` +
+          `packages/cli/docs/gsc.md for the current key shapes.`,
+        );
+      }
+      return {
+        token,
+        accountId,
+        account: overrides.account,
+        vaultKeys: { ...cand },
+      };
     }
   }
-  // None matched — error message lists the primary pair the operator
-  // is expected to set; legacy fallback is a back-compat courtesy, not
-  // a thing we advertise.
+
+  const primary = plan.candidates[0];
   throw new VaultError(
-    `Cloudflare vault keys not found. Pass --account <name> (e.g. --account stravica) ` +
-    `to use the per-account pair, or store the default pair:\n` +
-    `  secrets set ${VAULT_KEYS.tokenUnsuffixed} <token>\n` +
-    `  secrets set ${VAULT_KEYS.accountIdUnsuffixed} <id>`,
+    `--account "${overrides.account}" expects vault keys [${primary.tokenKey}, ${primary.accountIdKey}] ` +
+    `(or one of the fallback pairs listed in packages/cli/docs/gsc.md) but none are set. ` +
+    `Store them with:\n  secrets set ${primary.tokenKey} <token>\n  secrets set ${primary.accountIdKey} <id>`,
     1,
   );
 }

package/dist/engineering-pa-cli/src/staging-alias/sites.mjs

@@ -16,8 +16,10 @@
 //
 // `accountKey` is the vault-key suffix (lowercase form passed to
 // `loadCloudflareCreds({ account })`). The CF helper upper-cases it
-// internally to build `CLOUDFLARE_PAGES_API_KEY_<SUFFIX>` + matching
-// account-id key.
+// internally and tries the current candidate templates in order —
+// CLOUDFLARE_WORKERS_API_TOKEN_<SUFFIX>, then CLOUDFLARE_PAGES_API_
+// TOKEN_<SUFFIX>, then the deprecated CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
+// (see cloudflare.mjs for the full list and gsc.md for the rationale).
 
 /** @typedef {{
  *   hostname: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",