@descix/cli 1.0.1 → 1.0.3

package/lib/commands/auth.js

@@ -9,11 +9,13 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { DeSciXApiClient } from '../api-client.js';
 import { WalletFileManager } from '../wallet-file.js';
+import { walletEnvironmentStamp } from '../wallet-environment.js';
 import { WorkspaceConfig } from '../workspace-config.js';
 import { requireAuth } from '../auth-guard.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
+import { diag } from '../diagnostic-log.js';
 
 const execAsync = promisify(exec);
 const POLL_INTERVAL_MS = 3000; // 3 seconds
@@ -43,14 +45,47 @@ async function openBrowser(url) {
 }
 
 /**
- * Request device login via HTTP
+ * Request device login via HTTP.
+ * WS-HEADLESS-MVP-A1: optionally carries the device→OAuth bridge context so the server
+ * issues an OAuth authorization code alongside the session on completion (design §2.1).
  * @param {DeSciXApiClient} apiClient - The API client
+ * @param {Object|null} oauthCtx - { client_id, code_challenge, redirect_uri, scope }
  */
-async function requestDeviceLogin(apiClient) {
-  const response = await apiClient.invoke('device_request_login', {}, { allowGuest: true });
+async function requestDeviceLogin(apiClient, oauthCtx = null) {
+  const params = oauthCtx ? { oauth: oauthCtx } : {};
+  const response = await apiClient.invoke('device_request_login', params, { allowGuest: true });
   return response.message;
 }
 
+/**
+ * WS-HEADLESS-MVP-A1 — prepare the OAuth leg of `descix login`:
+ * PKCE pair + a registered CLI public client (DCR, reusing a cached client_id when the
+ * wallet file already has one). Returns null (with a loud warning) when the server does
+ * not expose the OAuth AS — the wallet-sig login proceeds untouched (design §4.1:
+ * "Behind a flag; wallet-sig path untouched").
+ */
+async function prepareOAuthLeg(apiClient, existingWallet, scope) {
+  const oauthClient = await import('../oauth-client.js');
+  const { verifier, challenge } = oauthClient.generatePkcePair();
+
+  let clientId = existingWallet?.oauth?.client_id || null;
+  if (!clientId) {
+    clientId = await oauthClient.registerOAuthClient(apiClient.baseUrl, {});
+  }
+
+  return {
+    oauthClient,
+    verifier,
+    clientId,
+    ctx: {
+      client_id: clientId,
+      code_challenge: challenge,
+      redirect_uri: oauthClient.OOB_REDIRECT_URI,
+      scope: scope || oauthClient.DEFAULT_OAUTH_SCOPE,
+    },
+  };
+}
+
 /**
  * Poll for device login completion via HTTP
  */
@@ -69,11 +104,16 @@ async function pollDeviceLogin(apiClient, deviceCode, onStatus = null) {
       if (status === 'complete') {
         return {
           user_id: response.message.user_id,
+          email: response.message.email || null,
           session_token: response.message.session_token,
           wallet_address: response.message.wallet_address,
           signature: response.message.signature,
-          community_id: response.message.community_id || 'descix',
-          token_symbol: response.message.token_symbol || 'DAITA'
+          community_id: response.message.community_id,
+          token_symbol: response.message.token_symbol || 'DAITA',
+          // WS-A1 device→OAuth bridge: single-use authorization code (present exactly once
+          // when the request carried an oauth ctx) — redeemed at /oauth/token immediately.
+          oauth_code: response.message.oauth_code || null,
+          oauth_scope: response.message.oauth_scope || null
         };
       }
       
@@ -102,13 +142,13 @@ async function pollDeviceLogin(apiClient, deviceCode, onStatus = null) {
 export async function loginDevice(options = {}) {
   const apiClient = new DeSciXApiClient({ baseUrl: options.url });
   
-  console.log(chalk.cyan('\n🔐 DeSciX Device Login\n'));
+  diag(chalk.cyan('\n🔐 DeSciX Device Login\n'));
   
   const spinner = ora('Requesting device login...').start();
   
   // Ensure we have the base URL resolved
   await apiClient.ensureBaseUrl();
-  console.log(chalk.gray(`   API: ${apiClient.baseUrl}\n`));
+  diag(chalk.gray(`   API: ${apiClient.baseUrl}\n`));
   
   try {
     // Detect workspace root
@@ -124,19 +164,45 @@ export async function loginDevice(options = {}) {
       workspaceRoot = foundRoot || startDir;
     }
 
-    // Request device login
-    const request = await requestDeviceLogin(apiClient);
+    // WS-HEADLESS-MVP-A1: OAuth leg (default ON, `--no-oauth` disables). Additive: any
+    // failure here warns loudly and the wallet-sig device login proceeds untouched.
+    let oauthLeg = null;
+    if (options.oauth !== false) {
+      try {
+        const existingWallet = await WalletFileManager.loadWalletFile(
+          WalletFileManager.getProjectWalletPath(workspaceRoot));
+        oauthLeg = await prepareOAuthLeg(apiClient, existingWallet, options.scope);
+      } catch (e) {
+        diag(chalk.yellow(`\n⚠️  OAuth token leg unavailable (${e.message}).`));
+        diag(chalk.yellow('   Proceeding with wallet-signature login only.\n'));
+      }
+    }
+
+    // Request device login (retry ONCE on a stale cached OAuth client_id)
+    let request;
+    try {
+      request = await requestDeviceLogin(apiClient, oauthLeg?.ctx || null);
+    } catch (e) {
+      if (oauthLeg && /invalid_client/.test(e.message || '')) {
+        // Cached client_id no longer registered server-side — re-register and retry.
+        oauthLeg.clientId = await oauthLeg.oauthClient.registerOAuthClient(apiClient.baseUrl, {});
+        oauthLeg.ctx.client_id = oauthLeg.clientId;
+        request = await requestDeviceLogin(apiClient, oauthLeg.ctx);
+      } else {
+        throw e;
+      }
+    }
 
     spinner.succeed('Device login request created');
 
-    console.log(chalk.yellow('\n📱 Browser will open automatically...\n'));
-    console.log(chalk.white('In the browser, you will need to:'));
-    console.log(chalk.gray('  1. Enter your email address'));
-    console.log(chalk.gray('  2. Verify your email with the code sent'));
-    console.log(chalk.gray('  3. Accept the Terms of Service'));
-    console.log(chalk.gray('  4. Connect your crypto wallet'));
-    console.log(chalk.gray('  5. Sign the message to prove wallet ownership'));
-    console.log('');
+    diag(chalk.yellow('\n📱 Browser will open automatically...\n'));
+    diag(chalk.white('In the browser, you will need to:'));
+    diag(chalk.gray('  1. Enter your email address'));
+    diag(chalk.gray('  2. Verify your email with the code sent'));
+    diag(chalk.gray('  3. Accept the Terms of Service'));
+    diag(chalk.gray('  4. Connect your crypto wallet'));
+    diag(chalk.gray('  5. Sign the message to prove wallet ownership'));
+    diag('');
 
     spinner.start('Opening browser...');
 
@@ -146,10 +212,10 @@ export async function loginDevice(options = {}) {
     const opened = await openBrowser(verificationUrl);
     if (opened) {
       spinner.succeed('Browser opened');
-      console.log(chalk.yellow(`\nURL: ${verificationUrl}\n`));
+      diag(chalk.yellow(`\nURL: ${verificationUrl}\n`));
     } else {
       spinner.warn('Could not open browser automatically');
-      console.log(chalk.yellow(`\nPlease open: ${verificationUrl}\n`));
+      diag(chalk.yellow(`\nPlease open: ${verificationUrl}\n`));
     }
 
     // Poll for completion
@@ -168,15 +234,45 @@ export async function loginDevice(options = {}) {
       userId: credentials.user_id,
       email: credentials.email,
       sessionToken: credentials.session_token,
-      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString()
+      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
+      // Record WHERE this credential was obtained. Write-only: nothing refuses on it yet.
+      ...walletEnvironmentStamp(apiClient.baseUrl)
     };
-    
+
+    // WS-HEADLESS-MVP-A1: redeem the device-bridge authorization code for the long-lived
+    // OAuth pair (design §3) and cache it gcloud-ADC-style in wallet.json. The AS's auth
+    // codes are single-use with a ≤60s TTL — redeem BEFORE anything else.
+    if (oauthLeg && credentials.oauth_code) {
+      try {
+        const tokens = await oauthLeg.oauthClient.redeemAuthorizationCode(apiClient.baseUrl, {
+          code: credentials.oauth_code,
+          clientId: oauthLeg.clientId,
+          codeVerifier: oauthLeg.verifier,
+        });
+        walletData.oauth = oauthLeg.oauthClient.buildOAuthCredentialBlock({
+          clientId: oauthLeg.clientId,
+          tokens,
+          tokenEndpointBase: apiClient.baseUrl,
+        });
+      } catch (e) {
+        diag(chalk.yellow(`\n⚠️  OAuth code redemption failed: ${e.message}`));
+        diag(chalk.yellow('   Wallet-signature login is still valid; re-run "descix login" for OAuth tokens.\n'));
+      }
+    } else if (oauthLeg && !credentials.oauth_code) {
+      diag(chalk.yellow('\n⚠️  Server did not issue an OAuth code (device→OAuth bridge not available).'));
+      diag(chalk.yellow('   Wallet-signature login is still valid.\n'));
+    }
+
     const walletPath = WalletFileManager.getProjectWalletPath(workspaceRoot);
     await WalletFileManager.saveWalletFile(walletPath, walletData);
-    
+
     spinner.succeed(chalk.green('Login successful!'));
-    console.log(chalk.cyan(`\n✅ Credentials saved to:`));
-    console.log(chalk.gray(`   ${walletPath}\n`));
+    if (walletData.oauth) {
+      diag(chalk.green('   OAuth tokens cached (30-day silent refresh — gcloud-style).'));
+      diag(chalk.gray(`   Scope: ${walletData.oauth.scope}`));
+    }
+    diag(chalk.cyan(`\n✅ Credentials saved to:`));
+    diag(chalk.gray(`   ${walletPath}\n`));
     
     // Sync auto-purchase apps
     spinner.start('Syncing app entitlements...');
@@ -198,28 +294,28 @@ export async function loginDevice(options = {}) {
       }
     } catch (error) {
       spinner.warn(chalk.yellow('Could not sync app entitlements'));
-      console.log(chalk.gray(`   ${error.message}\n`));
+      diag(chalk.gray(`   ${error.message}\n`));
     }
     
-    console.log(chalk.white('You can now use all DeSciX CLI commands!\n'));
+    diag(chalk.white('You can now use all DeSciX CLI commands!\n'));
 
   } catch (error) {
     spinner.fail(chalk.red('Login failed'));
     console.error(chalk.red(error.message));
     
     if (error.message.includes('expired')) {
-      console.log(chalk.yellow('💡 Tip: Device codes expire after 15 minutes.'));
-      console.log(chalk.yellow('   Run the login command again to get a new code.\n'));
+      diag(chalk.yellow('💡 Tip: Device codes expire after 15 minutes.'));
+      diag(chalk.yellow('   Run the login command again to get a new code.\n'));
     } else {
-      console.log(chalk.yellow('💡 Tip: Make sure you:'));
-      console.log(chalk.yellow('   - Have an internet connection'));
-      console.log(chalk.yellow('   - Can access the DeSciX platform'));
-      console.log(chalk.yellow('   - Complete all steps in the browser'));
-      console.log(chalk.yellow(`   - API URL is correct: ${apiClient.baseUrl || 'unknown'}`));
+      diag(chalk.yellow('💡 Tip: Make sure you:'));
+      diag(chalk.yellow('   - Have an internet connection'));
+      diag(chalk.yellow('   - Can access the DeSciX platform'));
+      diag(chalk.yellow('   - Complete all steps in the browser'));
+      diag(chalk.yellow(`   - API URL is correct: ${apiClient.baseUrl || 'unknown'}`));
       if (apiClient.baseUrl?.includes('localhost')) {
-        console.log(chalk.yellow('   - Local backend server is running'));
+        diag(chalk.yellow('   - Local backend server is running'));
       }
-      console.log('');
+      diag('');
     }
     throw error;
   }
@@ -229,11 +325,11 @@ export async function loginDevice(options = {}) {
  * Direct wallet login command (not yet implemented)
  */
 export async function loginWallet() {
-  console.log(chalk.cyan('\n🔐 DeSciX Wallet Login\n'));
-  console.log(chalk.yellow('\n⚠️  Direct wallet login requires a Web3 provider.\n'));
-  console.log(chalk.white('For CLI/MCP, device login is recommended:\n'));
-  console.log(chalk.cyan('  descix login\n'));
-  console.log(chalk.gray('This opens your browser where you can connect your wallet.\n'));
+  diag(chalk.cyan('\n🔐 DeSciX Wallet Login\n'));
+  diag(chalk.yellow('\n⚠️  Direct wallet login requires a Web3 provider.\n'));
+  diag(chalk.white('For CLI/MCP, device login is recommended:\n'));
+  diag(chalk.cyan('  descix login\n'));
+  diag(chalk.gray('This opens your browser where you can connect your wallet.\n'));
   throw new Error('Direct wallet login not yet implemented for CLI. Use device login instead.');
 }
 
@@ -284,10 +380,10 @@ export async function reconnect() {
     await WalletFileManager.saveWalletFile(walletPath, updatedWalletData);
     
     spinner.succeed(chalk.green('Reconnected successfully!'));
-    console.log(chalk.cyan(`\n✅ Status: ${result.auth_status || 'CONNECTED'}`));
-    console.log(chalk.gray(`   User: ${sessionInfo?.email || sessionInfo?.id || walletInfo.userId}`));
-    console.log(chalk.gray(`   Wallet: ${walletInfo.walletAddress?.substring(0, 10)}...`));
-    console.log(chalk.gray(`   Session refreshed\n`));
+    diag(chalk.cyan(`\n✅ Status: ${result.auth_status || 'CONNECTED'}`));
+    diag(chalk.gray(`   User: ${sessionInfo?.email || sessionInfo?.id || walletInfo.userId}`));
+    diag(chalk.gray(`   Wallet: ${walletInfo.walletAddress?.substring(0, 10)}...`));
+    diag(chalk.gray(`   Session refreshed\n`));
     
   } catch (error) {
     spinner.fail(chalk.red('Reconnection failed'));
@@ -307,7 +403,7 @@ export async function whoami() {
   try {
     await requireAuth(apiClient);
     
-    const response = await apiClient.invoke('check_staked_status', {}, { allowGuest: false });
+    const response = await apiClient.invoke('validate_session', {}, { allowGuest: false });
     const userInfo = response.message;
     
     const walletPath = await WalletFileManager.findWalletFile(process.cwd());
@@ -316,60 +412,60 @@ export async function whoami() {
     
     spinner.succeed(chalk.green('Authentication status'));
     
-    console.log(chalk.cyan('\n📋 Current Session:\n'));
-    console.log(chalk.white(`   User ID:    ${userInfo?.id || userInfo?.user_id || walletInfo?.userId || 'Unknown'}`));
-    console.log(chalk.white(`   Email:      ${userInfo?.email || walletInfo?.email || 'N/A'}`));
+    diag(chalk.cyan('\n📋 Current Session:\n'));
+    diag(chalk.white(`   User ID:    ${userInfo?.id || userInfo?.user_id || walletInfo?.userId || 'Unknown'}`));
+    diag(chalk.white(`   Email:      ${userInfo?.email || walletInfo?.email || 'N/A'}`));
     if (walletInfo) {
-      console.log(chalk.white(`   Wallet:     ${walletInfo.walletAddress?.substring(0, 10)}...${walletInfo.walletAddress?.slice(-6) || ''}`));
+      diag(chalk.white(`   Wallet:     ${walletInfo.walletAddress?.substring(0, 10)}...${walletInfo.walletAddress?.slice(-6) || ''}`));
       if (walletInfo.communityId) {
-        console.log(chalk.white(`   Community:  ${walletInfo.communityId}`));
+        diag(chalk.white(`   Community:  ${walletInfo.communityId}`));
       }
       if (walletInfo.tokenSymbol) {
-        console.log(chalk.white(`   Token:      ${walletInfo.tokenSymbol}`));
+        diag(chalk.white(`   Token:      ${walletInfo.tokenSymbol}`));
       }
-      console.log(chalk.white(`   Session:    ${isValid ? chalk.green('Valid') : chalk.red('Expired')}`));
+      diag(chalk.white(`   Session:    ${isValid ? chalk.green('Valid') : chalk.red('Expired')}`));
       
       if (walletInfo.expiresAt) {
         const expiresDate = new Date(walletInfo.expiresAt);
         const now = new Date();
         if (expiresDate > now) {
           const hoursLeft = Math.round((expiresDate - now) / (1000 * 60 * 60));
-          console.log(chalk.white(`   Expires:    ${hoursLeft}h remaining`));
+          diag(chalk.white(`   Expires:    ${hoursLeft}h remaining`));
         } else {
-          console.log(chalk.white(`   Expires:    ${chalk.red('Expired')}`));
+          diag(chalk.white(`   Expires:    ${chalk.red('Expired')}`));
         }
       }
     }
     
     if (userInfo) {
-      console.log(chalk.cyan('\n📊 Account Details:\n'));
-      console.log(chalk.white(`   Balance:    ${userInfo.custodial_usd_balance || userInfo.balance || 0} USDCX`));
-      console.log(chalk.white(`   Staked:     ${userInfo.is_staked ? chalk.green('Yes') : chalk.yellow('No')}`));
-      
+      // Account Details: feature access is entitlement-based (community membership / subscriptions),
+      // NOT a custodial balance or a STAKED state — both removed per CEO-D-2026-06-14-DROP-CUSTODIAL-ELIMINATE-STAKED.
+      diag(chalk.cyan('\n📊 Account Details:\n'));
+
       try {
         const purchasesResponse = await apiClient.invoke('fetch_my_purchases', { product_type: 'APP' }, { allowGuest: false });
         const purchases = purchasesResponse.message || {};
         const communities = purchases.communities || [];
         const apps = purchases.apps || purchases.products || [];
 
-        console.log(chalk.white(`   Communities: ${communities.length}`));
-        console.log(chalk.white(`   Apps:        ${apps.length}`));
+        diag(chalk.white(`   Communities: ${communities.length}`));
+        diag(chalk.white(`   Apps:        ${apps.length}`));
         if (apps.length > 0) {
           apps.slice(0, 5).forEach(a => {
             const id = a.app_id || a.appId || a.id || a.product_id;
-            if (id) console.log(chalk.gray(`               - ${id}`));
+            if (id) diag(chalk.gray(`               - ${id}`));
           });
-          if (apps.length > 5) console.log(chalk.gray(`               ... and ${apps.length - 5} more`));
+          if (apps.length > 5) diag(chalk.gray(`               ... and ${apps.length - 5} more`));
         }
       } catch (err) {
         // Ignore purchase fetch errors
       }
     }
     
-    console.log('');
+    diag('');
     
     if (walletInfo && !isValid) {
-      console.log(chalk.yellow('   ⚠️  Session expired. Run "descix reconnect" to refresh.\n'));
+      diag(chalk.yellow('   ⚠️  Session expired. Run "descix reconnect" to refresh.\n'));
     }
     
   } catch (error) {
@@ -380,28 +476,114 @@ export async function whoami() {
 }
 
 /**
- * Logout - clear credentials
+ * Logout - revoke server-side OAuth credentials (RFC 7009), then clear the local cache.
+ * WS-HEADLESS-MVP-A1 (design §4.6): revocation kills the whole refresh-token chain so a
+ * copied wallet.json cannot keep refreshing after logout. Revocation failure is reported
+ * but never blocks the local credential wipe.
  */
 export async function logout() {
   const spinner = ora('Logging out...').start();
-  
+
   try {
     const walletPath = await WalletFileManager.findWalletFile(process.cwd());
-    
+
     if (!walletPath) {
       spinner.info(chalk.yellow('Not logged in'));
-      console.log(chalk.gray('\n   No credentials to remove.\n'));
+      diag(chalk.gray('\n   No credentials to remove.\n'));
       return;
     }
-    
+
+    const walletInfo = await WalletFileManager.loadWalletFile(walletPath);
+    if (walletInfo?.oauth?.refresh_token) {
+      spinner.text = 'Revoking OAuth credentials...';
+      try {
+        const apiClient = new DeSciXApiClient();
+        await apiClient.ensureBaseUrl();
+        const { revokeOAuthToken } = await import('../oauth-client.js');
+        await revokeOAuthToken(apiClient.baseUrl, {
+          token: walletInfo.oauth.refresh_token,
+          clientId: walletInfo.oauth.client_id,
+        });
+        diag(chalk.gray('\n   OAuth refresh-token chain revoked server-side.'));
+      } catch (e) {
+        diag(chalk.yellow(`\n   ⚠️  OAuth revocation failed (${e.message}); removing local credentials anyway.`));
+      }
+    }
+
     await fs.unlink(walletPath);
-    
+
     spinner.succeed(chalk.green('Logged out'));
-    console.log(chalk.cyan('\n✅ Credentials removed\n'));
-    
+    diag(chalk.cyan('\n✅ Credentials removed\n'));
+
   } catch (error) {
     spinner.fail(chalk.red('Logout failed'));
     console.error(chalk.red(error.message));
     throw error;
   }
 }
+
+/**
+ * Admin bootstrap login — generates CLI credentials for platform admins
+ * without requiring the PWA device login / Powch flow.
+ * Requires email to be in the DESCIX_ADMIN_GROUP Google Group.
+ */
+export async function adminLogin(options = {}) {
+  const email = options.email;
+  if (!email) {
+    console.error(chalk.red('--email is required'));
+    process.exit(1);
+  }
+
+  const spinner = ora('Authenticating as admin...').start();
+
+  try {
+    const apiClient = new DeSciXApiClient();
+    await apiClient.ensureBaseUrl();
+
+    // admin_bootstrap_login is a bootstrap command: it must be sent guest-like,
+    // never carrying a previously-stored access_token. Targeting a DIFFERENT env
+    // than the one that minted the stored token (e.g. CLI configured for dev but
+    // logging into prod via --env prod) would otherwise send a token prod's auth
+    // middleware rejects with HTTP 401 BEFORE admin_bootstrap_login runs. Force
+    // guest by skipping the session token, same as device_request_login.
+    const result = await apiClient.invokeRaw('admin_bootstrap_login', { email }, null, { skipSessionCheck: true });
+    const data = result.data || result;
+
+    if (data.status === 'ERROR') {
+      spinner.fail(data.message || 'Admin login failed');
+      process.exit(1);
+    }
+
+    const info = data.message;
+    if (!info || !info.session_token) {
+      spinner.fail('Unexpected response from server');
+      process.exit(1);
+    }
+
+    const walletData = {
+      walletAddress: info.wallet_address,
+      signature: info.signature,
+      sessionToken: info.session_token,
+      userId: info.user_id,
+      email: info.email,
+      communityId: info.community_id,
+      tokenSymbol: info.token_symbol || 'DAITA',
+      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
+      // Record WHERE this credential was obtained. Write-only: nothing refuses on it yet.
+      ...walletEnvironmentStamp(apiClient.baseUrl),
+    };
+
+    // Save wallet.json
+    const workspaceRoot = await WorkspaceConfig.findWorkspaceRoot(process.cwd()) || process.cwd();
+    const walletPath = WalletFileManager.getProjectWalletPath(workspaceRoot);
+    await WalletFileManager.saveWalletFile(walletPath, walletData);
+
+    spinner.succeed(chalk.green(`Logged in as admin: ${email}`));
+    diag(chalk.dim(`  Wallet: ${walletData.walletAddress}`));
+    diag(chalk.dim(`  Session expires: ${walletData.expiresAt}`));
+    diag(chalk.dim(`  Credentials saved to: ${walletPath}`));
+  } catch (error) {
+    spinner.fail(error.message || 'Admin login failed');
+    process.exit(1);
+  }
+}

package/lib/commands/briefer/errors.js

@@ -0,0 +1,88 @@
+/**
+ * BrieferExtractorError — canonical hard-fail surface for the `descix briefer` CLI.
+ *
+ * Per WS-DESCIX-BRIEFER-CLI scope doc §2.3 ("Hard-fail philosophy"), every data
+ * source has exactly one extraction method and exactly one failure mode:
+ * HARD-FAIL with an actionable error message.
+ *
+ * Per feedback_no-hardcoded-fallbacks: NO fallback values, NO best-effort prose,
+ * NO try-catch-and-default. If a source moved or changed shape, the CLI exits
+ * non-zero and the canonical briefer file remains untouched.
+ *
+ * Stable error codes (per scope doc §2.3) — grep-friendly for diagnostics:
+ *   BRIEFER-SRC-NOT-FOUND   Source file missing / line range no longer matches
+ *   BRIEFER-GCLOUD-AUTH     gcloud auth missing or insufficient scope
+ *   BRIEFER-GCLOUD-FAIL     gcloud probe failed (auth/empty/timeout) when --env=demo|prod required it
+ *   BRIEFER-PARSE-FAIL      Source file present but construct unparseable
+ *   BRIEFER-DRIFT-DETECTED  --check diff against canonical briefer non-empty
+ *   BRIEFER-NEGATIVE-CLAIM  Briefer claims X does not exist, but found at Y:Z
+ *   BRIEFER-FIRESTORE       Firestore read via apifront failed
+ *   BRIEFER-NOT-IMPLEMENTED M1 stub — extractor scaffold-only, real impl in later milestone
+ *
+ * Per scope doc §2.3, every error message must include:
+ *   1. The exact source path + line range that was being read.
+ *   2. The construct shape that was expected.
+ *   3. What the operator should do to recover.
+ *   4. A stable error code from the list above.
+ */
+
+export const BRIEFER_ERROR_CODES = Object.freeze({
+  SRC_NOT_FOUND: 'BRIEFER-SRC-NOT-FOUND',
+  GCLOUD_AUTH: 'BRIEFER-GCLOUD-AUTH',
+  PARSE_FAIL: 'BRIEFER-PARSE-FAIL',
+  DRIFT_DETECTED: 'BRIEFER-DRIFT-DETECTED',
+  NEGATIVE_CLAIM: 'BRIEFER-NEGATIVE-CLAIM',
+  FIRESTORE: 'BRIEFER-FIRESTORE',
+  GCLOUD_FAIL: 'BRIEFER-GCLOUD-FAIL',
+  NOT_IMPLEMENTED: 'BRIEFER-NOT-IMPLEMENTED',
+  WORKSPACE_NOT_FOUND: 'BRIEFER-WORKSPACE-NOT-FOUND'
+});
+
+export class BrieferExtractorError extends Error {
+  /**
+   * @param {object} args
+   * @param {string} args.code       One of BRIEFER_ERROR_CODES (REQUIRED).
+   * @param {string} args.section    Briefer section being extracted (e.g., '§3 routing').
+   * @param {string} args.source     File path or 'gcloud' or 'firestore' (REQUIRED).
+   * @param {string} args.expected   Construct shape that was expected (REQUIRED).
+   * @param {string} args.recovery   Concrete next step for the operator (REQUIRED).
+   * @param {string} [args.detail]   Optional extra context (e.g., parser msg, exit code).
+   */
+  constructor({ code, section, source, expected, recovery, detail } = {}) {
+    if (!code || !Object.values(BRIEFER_ERROR_CODES).includes(code)) {
+      // Hard-fail loud on misuse — caller is constructing a bad error.
+      // We do NOT default the code; per feedback_no-hardcoded-fallbacks the
+      // absence of a code is itself a misconfiguration we want to surface.
+      throw new Error(
+        `BrieferExtractorError requires a valid 'code'. Got: ${JSON.stringify(code)}. ` +
+        `Valid codes: ${Object.values(BRIEFER_ERROR_CODES).join(', ')}.`
+      );
+    }
+    if (!source) {
+      throw new Error(`BrieferExtractorError requires a 'source' (file path / 'gcloud' / 'firestore').`);
+    }
+    if (!expected) {
+      throw new Error(`BrieferExtractorError requires an 'expected' construct shape description.`);
+    }
+    if (!recovery) {
+      throw new Error(`BrieferExtractorError requires a 'recovery' instruction for the operator.`);
+    }
+
+    const lines = [
+      `[${code}] ${section || '(section unspecified)'}`,
+      `  source:   ${source}`,
+      `  expected: ${expected}`,
+      `  recovery: ${recovery}`
+    ];
+    if (detail) lines.push(`  detail:   ${detail}`);
+
+    super(lines.join('\n'));
+    this.name = 'BrieferExtractorError';
+    this.code = code;
+    this.section = section || null;
+    this.source = source;
+    this.expected = expected;
+    this.recovery = recovery;
+    this.detail = detail || null;
+  }
+}