@littlebearapps/platform-admin-sdk 2.2.0 → 2.3.1

package/dist/check-upgrade.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pre-flight check for upgrades — detects potential issues before writing files.
+ *
+ * Checks for:
+ *   - Template naming collisions
+ *   - Placeholder values left in wrangler configs (e.g., "YOUR_DB_ID")
+ *   - Migration number conflicts
+ *   - Excluded files from the manifest
+ */
+import type { Tier } from './prompts.js';
+export interface CheckResult {
+    currentVersion: string;
+    targetVersion: string;
+    currentTier: string;
+    targetTier: string;
+    placeholders: string[];
+    collisions: string[];
+    migrationConflicts: string[];
+    excludedFiles: string[];
+    ok: boolean;
+}
+/**
+ * Run pre-flight checks for an upgrade without modifying any files.
+ *
+ * @param projectDir - Path to the project directory
+ * @param targetTier - Optional tier to upgrade to (defaults to current tier)
+ * @returns CheckResult with all detected issues
+ */
+export declare function checkUpgrade(projectDir: string, targetTier?: Tier): CheckResult;

package/dist/check-upgrade.js

@@ -0,0 +1,97 @@
+/**
+ * Pre-flight check for upgrades — detects potential issues before writing files.
+ *
+ * Checks for:
+ *   - Template naming collisions
+ *   - Placeholder values left in wrangler configs (e.g., "YOUR_DB_ID")
+ *   - Migration number conflicts
+ *   - Excluded files from the manifest
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectCollisions, SDK_VERSION, getFilesForTier, isMigrationFile } from './templates.js';
+import { readManifest, MANIFEST_FILENAME } from './manifest.js';
+import { findHighestMigration, getMigrationNumber } from './migrations.js';
+/** Patterns that indicate placeholder values left by scaffolding. */
+const PLACEHOLDER_PATTERNS = [
+    /YOUR_DB_ID/,
+    /YOUR_KV_ID/,
+    /YOUR_QUEUE_ID/,
+    /YOUR_R2_BUCKET/,
+    /PLACEHOLDER/,
+    /your-database-id/,
+    /your-kv-namespace-id/,
+    /your-queue-id/,
+];
+/**
+ * Run pre-flight checks for an upgrade without modifying any files.
+ *
+ * @param projectDir - Path to the project directory
+ * @param targetTier - Optional tier to upgrade to (defaults to current tier)
+ * @returns CheckResult with all detected issues
+ */
+export function checkUpgrade(projectDir, targetTier) {
+    const manifest = readManifest(projectDir);
+    if (!manifest) {
+        throw new Error(`No ${MANIFEST_FILENAME} found in ${projectDir}.\n` +
+            `Run \`platform-admin-sdk adopt\` first.`);
+    }
+    const effectiveTier = targetTier ?? manifest.tier;
+    const result = {
+        currentVersion: manifest.sdkVersion,
+        targetVersion: SDK_VERSION,
+        currentTier: manifest.tier,
+        targetTier: effectiveTier,
+        placeholders: [],
+        collisions: [],
+        migrationConflicts: [],
+        excludedFiles: [...(manifest.excludeFromUpgrade ?? [])],
+        ok: true,
+    };
+    // 1. Check for naming collisions
+    result.collisions = detectCollisions(effectiveTier);
+    // 2. Scan wrangler.*.jsonc files for placeholder values
+    if (existsSync(projectDir)) {
+        let dirEntries;
+        try {
+            dirEntries = readdirSync(projectDir);
+        }
+        catch {
+            dirEntries = [];
+        }
+        const wranglerFiles = dirEntries.filter((f) => f.startsWith('wrangler') && (f.endsWith('.jsonc') || f.endsWith('.json')));
+        for (const wf of wranglerFiles) {
+            const filePath = join(projectDir, wf);
+            const content = readFileSync(filePath, 'utf-8');
+            for (const pattern of PLACEHOLDER_PATTERNS) {
+                if (pattern.test(content)) {
+                    result.placeholders.push(`${wf}: contains ${pattern.source}`);
+                }
+            }
+        }
+    }
+    // 3. Check for migration conflicts
+    const migrationsDir = join(projectDir, 'storage/d1/migrations');
+    const userHighest = findHighestMigration(migrationsDir);
+    const files = getFilesForTier(effectiveTier);
+    const migrationFiles = files.filter((f) => isMigrationFile(f));
+    // Find new scaffold migrations that would need to be renumbered
+    const newScaffoldMigrations = migrationFiles.filter((f) => {
+        const num = getMigrationNumber(f.dest);
+        return num !== null && num > manifest.highestScaffoldMigration;
+    });
+    // Check if any new scaffold migration numbers overlap with existing user migrations
+    for (const mf of newScaffoldMigrations) {
+        const num = getMigrationNumber(mf.dest);
+        if (num !== null && num <= userHighest && num > manifest.highestScaffoldMigration) {
+            const filename = mf.dest.split('/').pop() ?? mf.dest;
+            result.migrationConflicts.push(`${filename} (number ${num}) overlaps with existing user migrations (highest: ${userHighest}) — will be renumbered`);
+        }
+    }
+    // 4. Determine overall ok status
+    result.ok =
+        result.collisions.length === 0 &&
+            result.placeholders.length === 0 &&
+            result.migrationConflicts.length === 0;
+    return result;
+}

package/dist/index.js

@@ -24,6 +24,7 @@ import { collectOptions, isValidTier } from './prompts.js';
 import { scaffold } from './scaffold.js';
 import { upgrade } from './upgrade.js';
 import { adopt } from './adopt.js';
+import { checkUpgrade } from './check-upgrade.js';
 import { SDK_VERSION } from './templates.js';
 const BANNER = `
   ${pc.bold(pc.cyan('Platform Admin SDK'))} — Cloudflare Cost Protection
@@ -109,11 +110,15 @@ const upgradeCmd = new Command('upgrade')
     });
     console.log();
     const total = result.created.length + result.updated.length + result.migrations.length;
-    if (total === 0 && result.skipped.length === 0) {
+    if (total === 0 && result.skipped.length === 0 && result.excluded.length === 0) {
         console.log(pc.green('  Already up to date.'));
     }
     else {
-        console.log(`  ${pc.green(`${result.created.length} created`)}, ${pc.cyan(`${result.updated.length} updated`)}, ${pc.yellow(`${result.skipped.length} skipped`)}, ${pc.green(`${result.migrations.length} migrations`)}`);
+        let summary = `  ${pc.green(`${result.created.length} created`)}, ${pc.cyan(`${result.updated.length} updated`)}, ${pc.yellow(`${result.skipped.length} skipped`)}, ${pc.green(`${result.migrations.length} migrations`)}`;
+        if (result.excluded.length > 0) {
+            summary += `, ${pc.dim(`${result.excluded.length} excluded`)}`;
+        }
+        console.log(summary);
     }
     if (result.removed.length > 0) {
         console.log(`  ${pc.yellow(`${result.removed.length} files removed from SDK (kept on disk)`)}`);
@@ -170,6 +175,55 @@ const adoptCmd = new Command('adopt')
     console.log(`  ${pc.dim('You can now run:')} ${pc.cyan('platform-admin-sdk upgrade')}`);
     console.log();
 });
+// --- Check-upgrade command ---
+const checkUpgradeCmd = new Command('check-upgrade')
+    .description('Pre-flight check for upgrades — detect issues without writing files')
+    .argument('[project-dir]', 'Path to the project directory', '.')
+    .option('--tier <tier>', 'Target tier to check against')
+    .action(async (projectDirArg, cmdOpts) => {
+    if (cmdOpts.tier && !isValidTier(cmdOpts.tier)) {
+        console.error(pc.red(`  Error: Invalid tier "${cmdOpts.tier}". Must be one of: minimal, standard, full`));
+        process.exit(1);
+    }
+    const projectDir = resolve(process.cwd(), projectDirArg);
+    console.log(`  ${pc.bold('Checking')}: ${projectDir}`);
+    console.log();
+    const result = checkUpgrade(projectDir, cmdOpts.tier);
+    console.log(`  ${pc.bold('Current')}: v${result.currentVersion} (${result.currentTier})`);
+    console.log(`  ${pc.bold('Target')}:  v${result.targetVersion} (${result.targetTier})`);
+    console.log();
+    if (result.collisions.length > 0) {
+        console.log(pc.red(`  Collisions (${result.collisions.length}):`));
+        for (const c of result.collisions)
+            console.log(`    - ${c}`);
+        console.log();
+    }
+    if (result.placeholders.length > 0) {
+        console.log(pc.yellow(`  Placeholders (${result.placeholders.length}):`));
+        for (const p of result.placeholders)
+            console.log(`    - ${p}`);
+        console.log();
+    }
+    if (result.migrationConflicts.length > 0) {
+        console.log(pc.yellow(`  Migration conflicts (${result.migrationConflicts.length}):`));
+        for (const m of result.migrationConflicts)
+            console.log(`    - ${m}`);
+        console.log();
+    }
+    if (result.excludedFiles.length > 0) {
+        console.log(pc.dim(`  Excluded files (${result.excludedFiles.length}):`));
+        for (const e of result.excludedFiles)
+            console.log(`    - ${e}`);
+        console.log();
+    }
+    if (result.ok) {
+        console.log(pc.green('  All checks passed. Safe to upgrade.'));
+    }
+    else {
+        console.log(pc.yellow('  Issues found. Review before upgrading.'));
+    }
+    console.log();
+});
 // --- Main program ---
 const program = new Command()
     .name('platform-admin-sdk')
@@ -177,12 +231,13 @@ const program = new Command()
     .version(SDK_VERSION)
     .addCommand(scaffoldCmd)
     .addCommand(upgradeCmd)
-    .addCommand(adoptCmd);
+    .addCommand(adoptCmd)
+    .addCommand(checkUpgradeCmd);
 async function main() {
     console.log(BANNER);
     // Backward compat: if first arg isn't a known subcommand, treat it as `scaffold <arg>`
     const args = process.argv.slice(2);
-    const subcommands = ['scaffold', 'upgrade', 'adopt', 'help', '--help', '-h', '--version', '-V'];
+    const subcommands = ['scaffold', 'upgrade', 'adopt', 'check-upgrade', 'help', '--help', '-h', '--version', '-V'];
     if (args.length > 0 && !subcommands.includes(args[0])) {
         // Inject 'scaffold' as the subcommand
         process.argv.splice(2, 0, 'scaffold');

package/dist/manifest.d.ts

@@ -28,6 +28,8 @@ export interface ScaffoldManifest {
     files: Record<string, string>;
     /** Highest migration number owned by the scaffolder (user migrations are higher). */
     highestScaffoldMigration: number;
+    /** Relative file paths to skip during upgrade (user-managed files). */
+    excludeFromUpgrade?: string[];
 }
 /** SHA-256 hash of file content. */
 export declare function hashContent(content: string): string;

package/dist/scaffold.js

@@ -6,7 +6,7 @@ import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import pc from 'picocolors';
-import { getFilesForTier, SDK_VERSION } from './templates.js';
+import { getFilesForTier, SDK_VERSION, detectCollisions } from './templates.js';
 import { hashContent, buildManifest, writeManifest, MANIFEST_FILENAME } from './manifest.js';
 import { findHighestMigration } from './migrations.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -35,6 +35,10 @@ export async function scaffold(options, outputDir) {
         }
         throw new Error(`Directory already exists: ${outputDir}`);
     }
+    const collisions = detectCollisions(options.tier);
+    if (collisions.length > 0) {
+        throw new Error(`Template naming collisions detected:\n${collisions.map((c) => `  - ${c}`).join('\n')}`);
+    }
     const templatesDir = getTemplatesDir();
     const files = getFilesForTier(options.tier);
     const context = {

package/dist/templates.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Tier } from './prompts.js';
 /** Single source of truth for the SDK version. */
-export declare const SDK_VERSION = "2.2.0";
+export declare const SDK_VERSION = "2.3.0";
 /** Returns true if `to` is the same or higher tier than `from`. */
 export declare function isTierUpgradeOrSame(from: Tier, to: Tier): boolean;
 /** Check if a template file is a numbered migration (not seed.sql). */
@@ -19,4 +19,9 @@ export interface TemplateFile {
     /** Whether this file uses Handlebars templating */
     template: boolean;
 }
+/**
+ * Detect naming collisions where two template files resolve to the same destination path.
+ * Returns an array of collision descriptions (empty = no collisions).
+ */
+export declare function detectCollisions(tier: Tier): string[];
 export declare function getFilesForTier(tier: Tier): TemplateFile[];

package/dist/templates.js

@@ -5,7 +5,7 @@
  * All other files are copied verbatim.
  */
 /** Single source of truth for the SDK version. */
-export const SDK_VERSION = '2.2.0';
+export const SDK_VERSION = '2.3.0';
 /** Tier ordering for upgrade validation. */
 const TIER_ORDER = { minimal: 0, standard: 1, full: 2 };
 /** Returns true if `to` is the same or higher tier than `from`. */
@@ -566,6 +566,26 @@ const FULL_FILES = [
     { src: 'full/tests/integration/r2-archive.test.ts', dest: 'tests/integration/r2-archive.test.ts', template: false },
     { src: 'full/tests/integration/feedback-schema.test.ts', dest: 'tests/integration/feedback-schema.test.ts', template: false },
 ];
+/**
+ * Detect naming collisions where two template files resolve to the same destination path.
+ * Returns an array of collision descriptions (empty = no collisions).
+ */
+export function detectCollisions(tier) {
+    const files = getFilesForTier(tier);
+    const seen = new Map();
+    const collisions = [];
+    for (const file of files) {
+        const dest = file.dest;
+        const existing = seen.get(dest);
+        if (existing) {
+            collisions.push(`"${existing}" and "${file.src}" both resolve to "${dest}"`);
+        }
+        else {
+            seen.set(dest, file.src);
+        }
+    }
+    return collisions;
+}
 export function getFilesForTier(tier) {
     const files = [...SHARED_FILES];
     if (tier === 'standard' || tier === 'full') {

package/dist/upgrade.d.ts

@@ -20,5 +20,6 @@ export interface UpgradeResult {
     skipped: string[];
     removed: string[];
     migrations: string[];
+    excluded: string[];
 }
 export declare function upgrade(projectDir: string, options?: UpgradeOptions): Promise<UpgradeResult>;

package/dist/upgrade.js

@@ -14,7 +14,7 @@ import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import pc from 'picocolors';
-import { getFilesForTier, SDK_VERSION, isMigrationFile, isTierUpgradeOrSame } from './templates.js';
+import { getFilesForTier, SDK_VERSION, isMigrationFile, isTierUpgradeOrSame, detectCollisions } from './templates.js';
 import { readManifest, writeManifest, buildManifest, hashContent, MANIFEST_FILENAME, } from './manifest.js';
 import { findHighestMigration, getMigrationNumber, planMigrations } from './migrations.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -46,7 +46,11 @@ export async function upgrade(projectDir, options = {}) {
     }
     if (manifest.sdkVersion === SDK_VERSION && manifest.tier === targetTier) {
         console.log(pc.green(`  Already up to date (SDK ${SDK_VERSION}, tier ${targetTier}).`));
-        return { created: [], updated: [], skipped: [], removed: [], migrations: [] };
+        return { created: [], updated: [], skipped: [], removed: [], migrations: [], excluded: [] };
+    }
+    const collisions = detectCollisions(targetTier);
+    if (collisions.length > 0) {
+        throw new Error(`Template naming collisions detected:\n${collisions.map((c) => `  - ${c}`).join('\n')}`);
     }
     const templatesDir = getTemplatesDir();
     const files = getFilesForTier(targetTier);
@@ -59,12 +63,14 @@ export async function upgrade(projectDir, options = {}) {
         defaultAssignee: manifest.context.defaultAssignee,
         sdkVersion: SDK_VERSION,
     };
+    const excludeSet = new Set(manifest.excludeFromUpgrade ?? []);
     const result = {
         created: [],
         updated: [],
         skipped: [],
         removed: [],
         migrations: [],
+        excluded: [],
     };
     // Separate regular files from migrations
     const regularFiles = files.filter((f) => !isMigrationFile(f));
@@ -75,6 +81,16 @@ export async function upgrade(projectDir, options = {}) {
         const srcPath = join(templatesDir, file.src);
         const destRelative = renderString(file.dest, context);
         const destPath = join(projectDir, destRelative);
+        if (excludeSet.has(destRelative)) {
+            console.log(`  ${pc.dim('exclude')} ${destRelative} ${pc.dim('(in excludeFromUpgrade)')}`);
+            result.excluded.push(destRelative);
+            // Preserve existing hash in new manifest if file is on disk
+            if (existsSync(destPath)) {
+                const diskContent = readFileSync(destPath, 'utf-8');
+                newFileHashes[destRelative] = hashContent(diskContent);
+            }
+            continue;
+        }
         if (!existsSync(srcPath))
             continue;
         const raw = readFileSync(srcPath, 'utf-8');
@@ -174,6 +190,9 @@ export async function upgrade(projectDir, options = {}) {
     // --- Write updated manifest ---
     if (!options.dryRun) {
         const newManifest = buildManifest(SDK_VERSION, targetTier, manifest.context, newFileHashes, highestScaffoldMig);
+        if (manifest.excludeFromUpgrade && manifest.excludeFromUpgrade.length > 0) {
+            newManifest.excludeFromUpgrade = manifest.excludeFromUpgrade;
+        }
         writeManifest(projectDir, newManifest);
     }
     return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/platform-admin-sdk",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Platform Admin SDK — scaffold backend infrastructure with workers, circuit breakers, and cost protection for Cloudflare",
   "type": "module",
   "bin": {

package/templates/full/workers/platform-alert-router.ts

@@ -1187,10 +1187,10 @@ async function findExistingIssue(
     const alertNumber = alert.metadata?.alert_number as number;
     const ruleId = alert.metadata?.rule_id as string;
 
-    const query = `repo:${owner}/${repo} is:issue is:open label:codeql "${ruleId}" in:title "${alertNumber}" in:body`;
-
+    // Use Issues List API (not Search API) — more reliable with GitHub App tokens.
+    const labelParam = encodeURIComponent('codeql');
     const response = await fetch(
-      `https://api.github.com/search/issues?q=${encodeURIComponent(query)}`,
+      `https://api.github.com/repos/${owner}/${repo}/issues?labels=${labelParam}&state=open&per_page=10&sort=created&direction=desc`,
       {
         headers: {
           Authorization: `Bearer ${env.GITHUB_TOKEN}`,
@@ -1201,16 +1201,15 @@ async function findExistingIssue(
     );
 
     if (!response.ok) {
-      log.error('Failed to search for existing issues', { status: response.status });
+      log.error('Failed to list issues by label', { status: response.status });
       return null;
     }
 
-    const data = (await response.json()) as {
-      items?: Array<{ number: number; title: string; body: string }>;
-    };
+    const data = (await response.json()) as
+      Array<{ number: number; title: string; body: string }>;
 
     // Check if any results match this alert number
-    const match = data.items?.find((issue) =>
+    const match = data.find((issue) =>
       issue.body?.includes(`Alert Number**: #${alertNumber}`)
     );
 

package/templates/standard/workers/lib/error-collector/email-health-alerts.ts

@@ -200,16 +200,13 @@ export async function processEmailHealthAlerts(
     try {
       const issueTitle = `Email Health: ${brandName} ${failure.check_type} failing`;
 
-      // Search for an existing OPEN issue before creating a new one.
-      // This prevents daily duplicate issues when a problem persists across days.
-      const openIssues = await github.searchIssues(
-        owner,
-        repo,
-        `"${issueTitle}" is:open label:cf:email-health`
-      );
+      // List existing OPEN email health issues before creating a new one.
+      // Uses Issues List API (not Search API) — more reliable with GitHub App tokens.
+      const openIssues = await github.listIssuesByLabel(owner, repo, ['cf:email-health'], 'open');
+      const matchingIssue = openIssues.find((issue) => issue.title === issueTitle);
 
-      if (openIssues.length > 0) {
-        const existing = openIssues[0];
+      if (matchingIssue) {
+        const existing = matchingIssue;
         await github.addComment(
           owner,
           repo,

package/templates/standard/workers/lib/error-collector/gap-alerts.ts

@@ -237,16 +237,15 @@ export async function processGapAlert(
   const github = new GitHubClient(env);
 
   try {
-    // Search for an existing OPEN gap alert issue before creating a new one.
-    // This prevents daily duplicate issues when coverage stays below threshold.
-    const openIssues = await github.searchIssues(
-      owner,
-      repo,
-      `"Data Coverage Gap: ${event.project}" is:open label:cf:gap-alert`
+    // List existing OPEN gap alert issues before creating a new one.
+    // Uses Issues List API (not Search API) — more reliable with GitHub App tokens.
+    const openIssues = await github.listIssuesByLabel(owner, repo, ['cf:gap-alert'], 'open');
+    const matchingIssue = openIssues.find((issue) =>
+      issue.title.includes(`Data Coverage Gap: ${event.project}`)
     );
 
-    if (openIssues.length > 0) {
-      const existing = openIssues[0];
+    if (matchingIssue) {
+      const existing = matchingIssue;
       await github.addComment(
         owner,
         repo,

package/templates/standard/workers/lib/error-collector/github.ts

@@ -277,6 +277,32 @@ export class GitHubClient {
     return this.request('GET', `/repos/${owner}/${repo}/issues/${issueNumber}`);
   }
 
+  /**
+   * List issues filtered by labels using the Issues List API.
+   * More reliable than Search API with GitHub App installation tokens.
+   * @see https://docs.github.com/en/rest/issues/issues#list-repository-issues
+   */
+  async listIssuesByLabel(
+    owner: string,
+    repo: string,
+    labels: string[],
+    state: 'open' | 'closed' = 'open'
+  ): Promise<
+    Array<{
+      number: number;
+      state: string;
+      title: string;
+      body: string | null;
+      labels: Array<{ name: string }>;
+    }>
+  > {
+    const labelParam = labels.join(',');
+    return this.request(
+      'GET',
+      `/repos/${owner}/${repo}/issues?labels=${encodeURIComponent(labelParam)}&state=${state}&per_page=10&sort=created&direction=desc`
+    );
+  }
+
   /**
    * Search for issues using GitHub's search API.
    * Retries once on 403 (rate limit) with a 1s delay.