ci fixes (#871)

- **update working agreement**
- **improve robustness of asset lookup...**
- **fix: load timing issues w/ environment vars**

Author: NiloCK

agent/u.working-agreement.md

@@ -1,7 +1,9 @@
-This folder is the working scratchpad for user+assistant development.
+This folder is the working scratchpad for document-centric user+assistant development.
 
 # Conventions
 
+Working sessions will usually be focused on a session-directory. Either a numbered directory (referring to a gh issue) or a directory named for the task at hand. New working documents should be created in this directory, and named according to the conventions below. For GH issues, please *do* use the `gh` command to *read* existing issues, PRs, and workflow runs.
+
 files prefixed with `u.` are user-authored.
 files prefixed with `a.` are assistant-authored.
 

packages/express/src/app.ts

@@ -1,18 +1,21 @@
-import { createExpressApp, initializeServices } from './app-factory.js';
-import logger from './logger.js';
-import ENV from './utils/env.js';
 import dotenv from 'dotenv';
-import { initializeCouchDB } from './couchdb/index.js';
-import { initializeDataLayer } from '@vue-skuilder/db';
 
+// Load environment variables FIRST before importing any modules that depend on them
 dotenv.config({
   path:
     process.argv && process.argv.length == 3
       ? process.argv[2]
       : '.env.development',
 });
 
-// Now that dotenv is configured, we can validate the environment
+// Now import modules that depend on environment variables
+import { createExpressApp, initializeServices } from './app-factory.js';
+import logger from './logger.js';
+import ENV from './utils/env.js';
+import { initializeCouchDB } from './couchdb/index.js';
+import { initializeDataLayer } from '@vue-skuilder/db';
+
+// Validate that environment variables are loaded
 const requiredVars = ['COUCHDB_SERVER', 'COUCHDB_PROTOCOL', 'COUCHDB_ADMIN', 'COUCHDB_PASSWORD', 'VERSION', 'NODE_ENV'];
 const missingVars = requiredVars.filter(v => !process.env[v]);
 

packages/express/src/design-docs.ts

@@ -15,19 +15,42 @@ function emit(key?: unknown, value?: unknown): [unknown, unknown] {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Load design documents with absolute paths
+// Dual resolution strategy for assets
+function getAssetPath(assetName: string): string {
+  // Strategy 1: Development mode - assets in parent directory
+  const devModePath = join(__dirname, '..', 'assets', assetName);
+  if (fileSystem.existsSync(devModePath)) {
+    return devModePath;
+  }
+  
+  // Strategy 2: Built module mode - assets in same directory
+  const moduleModePath = join(__dirname, 'assets', assetName);
+  if (fileSystem.existsSync(moduleModePath)) {
+    return moduleModePath;
+  }
+  
+  // Fallback error with helpful context
+  throw new Error(
+    `Asset '${assetName}' not found. Tried:\n` +
+    `  Dev mode: ${devModePath}\n` +
+    `  Module mode: ${moduleModePath}\n` +
+    `  Current __dirname: ${__dirname}`
+  );
+}
+
+// Load design documents with dual resolution
 export const classroomDbDesignDoc = fileSystem.readFileSync(
-  join(__dirname, 'assets', 'classroomDesignDoc.js'),
+  getAssetPath('classroomDesignDoc.js'),
   'utf-8'
 );
 
 export const courseDBDesignDoc = fileSystem.readFileSync(
-  join(__dirname, 'assets', 'get-tagsDesignDoc.json'),
+  getAssetPath('get-tagsDesignDoc.json'),
   'utf-8'
 );
 
 export const courseValidateDocUpdate = fileSystem.readFileSync(
-  join(__dirname, 'assets', 'courseValidateDocUpdate.js'),
+  getAssetPath('courseValidateDocUpdate.js'),
   'utf-8'
 );
 

packages/express/src/utils/env.ts

@@ -20,13 +20,14 @@ function getVar(name: string): string {
   }
 }
 
+// Use getter to read environment variables lazily after dotenv has loaded
 const env: Env = {
-  COUCHDB_SERVER: getVar('COUCHDB_SERVER'),
-  COUCHDB_PROTOCOL: getVar('COUCHDB_PROTOCOL'),
-  COUCHDB_ADMIN: getVar('COUCHDB_ADMIN'),
-  COUCHDB_PASSWORD: getVar('COUCHDB_PASSWORD'),
-  VERSION: getVar('VERSION'),
-  NODE_ENV: getVar('NODE_ENV'),
+  get COUCHDB_SERVER() { return getVar('COUCHDB_SERVER'); },
+  get COUCHDB_PROTOCOL() { return getVar('COUCHDB_PROTOCOL'); },
+  get COUCHDB_ADMIN() { return getVar('COUCHDB_ADMIN'); },
+  get COUCHDB_PASSWORD() { return getVar('COUCHDB_PASSWORD'); },
+  get VERSION() { return getVar('VERSION'); },
+  get NODE_ENV() { return getVar('NODE_ENV'); },
 };
 
 export default env;