@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/tools/setup-review.js

@@ -17,25 +17,30 @@ let tokenNameCounter = 0;
 const REVIEW_TOKEN_SCOPES = ['write:user', 'write:repository', 'write:issue', 'write:organization'];
 const PASSWORD_PROMPT_OPTIONS = { hidden: false };
 
+/** @param {string} repo @returns {{owner: string, repo: string}|null} */
 function parseRepoSlug(repo) {
-  if (typeof repo !== 'string') return null;
+  if (typeof repo !== 'string') {return null;}
   const match = repo.trim().match(/^([^/\s]+)\/([^/\s]+)$/);
-  if (!match) return null;
+  if (!match) {return null;}
   return { owner: match[1], repo: match[2] };
 }
 
+/** @param {string[]} values @returns {string[]} */
 function unique(values) {
   return [...new Set(values.filter(Boolean))];
 }
 
+/** @param {string|undefined} baseUrl @returns {string|undefined} */
 function normalizeBaseUrl(baseUrl) {
   return typeof baseUrl === 'string' ? baseUrl.replace(/\/+$/, '') : baseUrl;
 }
 
+/** @param {string} repoName @param {string} user @param {string} [suffix] @returns {string} */
 function buildTokenName(repoName, user, suffix = `${Date.now()}-${++tokenNameCounter}`) {
   return `workflow-${repoName}-${user}-${suffix}`;
 }
 
+/** @param {string} user @param {{allowBlank?: boolean}} [options] @returns {string} */
 function passwordPrompt(user, options = {}) {
   const { allowBlank = false } = options;
   return allowBlank
@@ -43,22 +48,30 @@ function passwordPrompt(user, options = {}) {
     : `Password for ${user} (input visible): `;
 }
 
+/** @param {string|undefined} value @param {boolean} [defaultValue] @returns {boolean} */
 function parseYesNo(value, defaultValue = true) {
-  if (typeof value !== 'string' || value.trim() === '') return defaultValue;
+  if (typeof value !== 'string' || value.trim() === '') {return defaultValue;}
   const normalized = value.trim().toLowerCase();
-  if (['y', 'yes'].includes(normalized)) return true;
-  if (['n', 'no'].includes(normalized)) return false;
+  if (['y', 'yes'].includes(normalized)) {return true;}
+  if (['n', 'no'].includes(normalized)) {return false;}
   return defaultValue;
 }
 
+/** @param {string} [rootDir] @returns {string} */
 function defaultProductName(rootDir = process.cwd()) {
   return path.basename(rootDir) || 'Workflow Project';
 }
 
+/** @param {string} [rootDir] @param {string} [ownerLogin] @returns {string} */
 function defaultRepoSlug(rootDir = process.cwd(), ownerLogin = 'human') {
   return `${ownerLogin}/${path.basename(rootDir) || 'project'}`;
 }
 
+/**
+ * @param {string} rootDir
+ * @param {{spawnSyncFn?: Function, configuredPrimaryBranch?: string|null}} [options]
+ * @returns {string}
+ */
 function detectPrimaryBranchDefault(rootDir = process.cwd(), options = {}) {
   const { spawnSyncFn = spawnSync, configuredPrimaryBranch = null } = options;
   const listResult = spawnSyncFn(
@@ -67,7 +80,7 @@ function detectPrimaryBranchDefault(rootDir = process.cwd(), options = {}) {
     { encoding: 'utf8' }
   );
   const branches = listResult.status === 0
-    ? (listResult.stdout || '').split('\n').map(value => value.trim()).filter(Boolean)
+    ? (listResult.stdout || '').split('\n').map(/** @param {string} value */ value => value.trim()).filter(Boolean)
     : [];
 
   if (configuredPrimaryBranch && branches.includes(configuredPrimaryBranch)) {
@@ -82,9 +95,9 @@ function detectPrimaryBranchDefault(rootDir = process.cwd(), options = {}) {
     return currentBranch;
   }
 
-  if (branches.includes('main')) return 'main';
-  if (branches.includes('master')) return 'master';
-  if (configuredPrimaryBranch) return configuredPrimaryBranch;
+  if (branches.includes('main')) {return 'main';}
+  if (branches.includes('master')) {return 'master';}
+  if (configuredPrimaryBranch) {return configuredPrimaryBranch;}
   return 'main';
 }
 
@@ -98,6 +111,7 @@ function standardLayoutDescription() {
   ].join('; ');
 }
 
+/** @param {{reviewProvider?: string, baseUrl?: string, reviewRemote?: string, reviewRepo?: string}} answers @returns {{provider: string, baseUrl?: string, remote?: string, repo?: string}} */
 function buildReviewAdapterConfig(answers) {
   const provider = answers.reviewProvider || 'forgejo';
   if (provider !== 'forgejo') {
@@ -111,11 +125,13 @@ function buildReviewAdapterConfig(answers) {
   };
 }
 
+/** @param {{missionsBaseDir?: string, branchPrefix?: string, worktreePattern?: string, primaryBranch?: string, productName?: string, tasksProvider?: string, tasksStorage?: string, verificationCommand?: string, verificationDefaultArea?: string, reviewProvider?: string, baseUrl?: string, reviewRemote?: string, reviewRepo?: string}} answers @returns {{product: {name: string, targetUser: string}, adapters: {tasks: {provider: string, storage: string}, missions: {baseDir: string, branchPrefix: string, worktreePattern: string, primaryBranch?: string}, verification: {command: string, defaultArea: string}, review: {provider: string, baseUrl?: string, remote?: string, repo?: string}, agents: {}}}} */
 function buildWorkflowConfig(answers) {
+  /** @type {{baseDir: string, branchPrefix: string, worktreePattern: string, primaryBranch?: string}} */
   const missions = {
-    baseDir: answers.missionsBaseDir,
-    branchPrefix: answers.branchPrefix,
-    worktreePattern: answers.worktreePattern,
+    baseDir: /** @type {string} */ (answers.missionsBaseDir),
+    branchPrefix: /** @type {string} */ (answers.branchPrefix),
+    worktreePattern: /** @type {string} */ (answers.worktreePattern),
   };
   if (
     typeof answers.primaryBranch === 'string' &&
@@ -127,18 +143,18 @@ function buildWorkflowConfig(answers) {
 
   return {
     product: {
-      name: answers.productName,
+      name: /** @type {string} */ (answers.productName),
       targetUser: 'Engineering teams using git, task tracking, and code review',
     },
     adapters: {
       tasks: {
-        provider: answers.tasksProvider,
-        storage: answers.tasksStorage,
+        provider: /** @type {string} */ (answers.tasksProvider),
+        storage: /** @type {string} */ (answers.tasksStorage),
       },
       missions,
       verification: {
-        command: answers.verificationCommand,
-        defaultArea: answers.verificationDefaultArea,
+        command: /** @type {string} */ (answers.verificationCommand),
+        defaultArea: /** @type {string} */ (answers.verificationDefaultArea),
       },
       review: buildReviewAdapterConfig(answers),
       agents: {},
@@ -146,12 +162,14 @@ function buildWorkflowConfig(answers) {
   };
 }
 
+/** @param {string} rootDir @param {{[key: string]: any}} config @returns {string} */
 function writeWorkflowConfig(rootDir, config) {
   const configPath = path.join(rootDir, 'workflow.config.json');
   fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
   return configPath;
 }
 
+/** @returns {string[]} */
 function suggestedForgejoUsers() {
   return unique([
     ...eligibleAgentsForStep('active'),
@@ -159,18 +177,21 @@ function suggestedForgejoUsers() {
   ]);
 }
 
+/** @param {string} user @param {string} [forgejoHome] @returns {string} */
 function tokenFilePath(user, forgejoHome = resolveForgejoHome()) {
   return path.join(forgejoHome, 'tokens', user);
 }
 
+/** @param {string} [forgejoHome] @returns {string} */
 function ensureTokenDir(forgejoHome = resolveForgejoHome()) {
   const dir = path.join(forgejoHome, 'tokens');
   fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
 
+/** @param {string} [rootDir] @param {string} [explicitForgejoHome] @returns {string} */
 function resolveBootstrapForgejoHome(rootDir = process.cwd(), explicitForgejoHome) {
-  if (explicitForgejoHome) return explicitForgejoHome;
+  if (explicitForgejoHome) {return explicitForgejoHome;}
   return path.join(rootDir, '.forgejo-local');
 }
 
@@ -178,10 +199,15 @@ function readConfiguredReviewRemote(rootDir = process.cwd(), remoteName = 'revie
   const result = spawnSync('git', ['-C', rootDir, 'remote', 'get-url', remoteName], {
     encoding: 'utf8',
   });
-  if (result.status !== 0) return null;
+  if (result.status !== 0) {return null;}
   return (result.stdout || '').trim() || null;
 }
 
+/**
+ * @param {string} rootDir
+ * @param {{users?: string[], remoteName?: string, remoteUrlFn?: Function, getRemoteUrlFn?: Function, tokenPathFn?: Function, requestFn?: Function}} [options]
+ * @returns {{required: boolean, ok: boolean, issues: string[], steps: string[]}}
+ */
 function evaluateReviewSetup(rootDir = process.cwd(), options = {}) {
   const {
     users = suggestedForgejoUsers(),
@@ -214,7 +240,7 @@ function evaluateReviewSetup(rootDir = process.cwd(), options = {}) {
   const configuredRemoteName = remoteName || reviewAdapter.remote || 'review';
   const issues = [];
   const steps = [];
-  const missingUsers = users.filter(user => !fs.existsSync(tokenPathFn(user)));
+  const missingUsers = users.filter(/** @param {string} user */ user => !fs.existsSync(tokenPathFn(user)));
 
   if (missingUsers.length > 0) {
     issues.push(`missing Forgejo tokens for: ${missingUsers.join(', ')}`);
@@ -247,7 +273,7 @@ function evaluateReviewSetup(rootDir = process.cwd(), options = {}) {
       } else if (!probe.ok && probe.statusCode === 404) {
         issues.push(`Forgejo review repo ${review.repo} is missing or inaccessible for ${user}`);
         steps.push('Run `px setup` to recreate the review repo and refresh token/remote wiring.');
-      } else if (!probe.ok && probe.statusCode == null) {
+      } else if (!probe.ok && probe.statusCode === null) {
         issues.push(`Forgejo at ${normalizedBaseUrl} is unreachable while validating ${user}`);
         steps.push('Start Forgejo and rerun `px verify-env` or `px setup-review`.');
       }
@@ -261,6 +287,12 @@ function evaluateReviewSetup(rootDir = process.cwd(), options = {}) {
   return { required: true, ok: false, issues, steps };
 }
 
+/**
+ * @param {string} method
+ * @param {string} requestUrl
+ * @param {{basicAuth?: {user: string, password: string}, token?: string, body?: {[key: string]: any}}} [options]
+ * @returns {{ok: boolean, statusCode: number|null, data: any, error: string|null}}
+ */
 function apiRequest(method, requestUrl, options = {}) {
   const args = [
     '-s',
@@ -288,6 +320,7 @@ function apiRequest(method, requestUrl, options = {}) {
     return {
       ok: false,
       statusCode: null,
+      data: null,
       error: (result.stderr || result.stdout || 'curl failed').trim(),
     };
   }
@@ -314,6 +347,7 @@ function apiRequest(method, requestUrl, options = {}) {
   };
 }
 
+/** @param {string} baseUrl @param {string} user @param {string} password @param {string} tokenName @param {Function} [requestFn] @param {string[]} [scopes] @returns {{ok: boolean, token?: string, error?: string, statusCode?: number|null, response?: any}} */
 function createToken(baseUrl, user, password, tokenName, requestFn = apiRequest, scopes = REVIEW_TOKEN_SCOPES) {
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
   const result = requestFn('POST', `${normalizedBaseUrl}/api/v1/users/${encodeURIComponent(user)}/tokens`, {
@@ -340,6 +374,7 @@ function createToken(baseUrl, user, password, tokenName, requestFn = apiRequest,
   return { ok: true, token };
 }
 
+/** @param {string} baseUrl @param {string} repoSlug @param {string} ownerLogin @param {string} ownerToken @param {Function} [requestFn] @returns {{ok: boolean, created?: boolean, error?: string, response?: any}} */
 function ensureRepo(baseUrl, repoSlug, ownerLogin, ownerToken, requestFn = apiRequest) {
   const repoInfo = parseRepoSlug(repoSlug);
   if (!repoInfo) {
@@ -379,6 +414,7 @@ function ensureRepo(baseUrl, repoSlug, ownerLogin, ownerToken, requestFn = apiRe
   return { ok: true, created: true };
 }
 
+/** @param {string} baseUrl @param {string} repoSlug @param {string} ownerToken @param {string} collaborator @param {string} [permission] @param {Function} [requestFn] @returns {{ok: boolean, created?: boolean, skipped?: boolean, error?: string, response?: any}} */
 function ensureRepoCollaborator(baseUrl, repoSlug, ownerToken, collaborator, permission = 'write', requestFn = apiRequest) {
   const repoInfo = parseRepoSlug(repoSlug);
   if (!repoInfo) {
@@ -403,13 +439,14 @@ function ensureRepoCollaborator(baseUrl, repoSlug, ownerToken, collaborator, per
   return { ok: true, created: true };
 }
 
+/** @param {string} baseUrl @param {string} repoSlug @param {string} ownerToken @param {string[]} [collaborators] @param {string} [permission] @param {Function} [requestFn] @returns {{ok: boolean, created: string[]}} */
 function ensureRepoCollaborators(baseUrl, repoSlug, ownerToken, collaborators = [], permission = 'write', requestFn = apiRequest) {
-  const uniqueCollaborators = unique(collaborators.map(user => (typeof user === 'string' ? user.trim() : '')).filter(Boolean));
+  const uniqueCollaborators = unique(collaborators.map(/** @param {string|boolean} user */ user => (typeof user === 'string' ? user.trim() : '')).filter(Boolean));
   const created = [];
   for (const collaborator of uniqueCollaborators) {
     const result = ensureRepoCollaborator(baseUrl, repoSlug, ownerToken, collaborator, permission, requestFn);
     if (!result.ok) {
-      return result;
+      return { ok: false, created: [] };
     }
     if (result.created) {
       created.push(collaborator);
@@ -418,6 +455,7 @@ function ensureRepoCollaborators(baseUrl, repoSlug, ownerToken, collaborators =
   return { ok: true, created };
 }
 
+/** @param {string} rootDir @param {string} remoteName @param {string} remoteUrl @returns {{ok: boolean, created?: boolean, updated?: boolean, error?: string}} */
 function ensureReviewRemote(rootDir, remoteName, remoteUrl) {
   const current = readConfiguredReviewRemote(rootDir, remoteName);
   const args = current
@@ -433,6 +471,11 @@ function ensureReviewRemote(rootDir, remoteName, remoteUrl) {
   return { ok: true, created: !current, updated: Boolean(current && current !== remoteUrl) };
 }
 
+/**
+ * @param {string} prompt
+ * @param {{hidden?: boolean, input?: NodeJS.ReadStream, output?: NodeJS.WriteStream}} [options]
+ * @returns {Promise<string>}
+ */
 async function promptLine(prompt, options = {}) {
   const { hidden = false, input = process.stdin, output = process.stdout } = options;
   return await new Promise((resolve) => {
@@ -446,7 +489,7 @@ async function promptLine(prompt, options = {}) {
     }
 
     const originalWrite = output.write.bind(output);
-    const maskChunk = (chunk) => {
+    const maskChunk = /** @param {string|Buffer} chunk */ (chunk) => {
       const value = typeof chunk === 'string' ? chunk : String(chunk);
       let masked = '';
       for (const character of value) {
@@ -464,18 +507,22 @@ async function promptLine(prompt, options = {}) {
       }
       return masked;
     };
-    output.write = (chunk, encoding, cb) => {
-      if (rl.stdoutMuted) {
-        const masked = maskChunk(chunk);
+    /** @type {import('readline').Interface & {stdoutMuted?: boolean}} */
+    const rlAny = rl;
+    /** @type {Function} */
+    // @ts-expect-error overriding Writable.write with custom signature
+    output.write = /** @type {any} */ ((chunk, encoding, cb) => {
+      if (rlAny.stdoutMuted) {
+        const masked = maskChunk(/** @type {string | Buffer} */ (chunk));
         if (masked) {
-          return originalWrite(masked, encoding, cb);
+          return /** @type {Function} */ (originalWrite)(masked, encoding, cb);
         }
-        if (typeof cb === 'function') cb();
+        if (typeof cb === 'function') {cb();}
         return true;
       }
-      return originalWrite(chunk, encoding, cb);
-    };
-    rl.stdoutMuted = true;
+      return /** @type {Function} */ (originalWrite)(chunk, encoding, cb);
+    });
+    rlAny.stdoutMuted = true;
     originalWrite(prompt);
     rl.question('', answer => {
       output.write = originalWrite;
@@ -486,10 +533,18 @@ async function promptLine(prompt, options = {}) {
   });
 }
 
+/** @param {{statusCode?: number}} result @returns {boolean} */
 function isAuthFailure(result) {
   return Boolean(result && (result.statusCode === 401 || result.statusCode === 403));
 }
 
+/**
+ * @param {{baseUrl: string, repo: string, ownerLogin: string, ownerPassword: string}} setup
+ * @param {string} user
+ * @param {string} initialPassword
+ * @param {{allowBlank?: boolean, log?: Function, promptFn?: Function, maxAttempts?: number, requestFn?: Function, scopes?: string[]}} [options]
+ * @returns {Promise<{ok: boolean, token?: string, error?: string, skipped?: boolean, statusCode?: number|null, response?: any}>}
+ */
 async function createTokenWithRetries(setup, user, initialPassword, options = {}) {
   const {
     allowBlank = false,
@@ -538,8 +593,8 @@ async function createTokenWithRetries(setup, user, initialPassword, options = {}
       requestFn,
       scopes
     );
-    if (tokenResult.ok) return tokenResult;
-    if (!isAuthFailure(tokenResult) || attempt === maxAttempts || typeof promptFn !== 'function') {
+    if (tokenResult.ok) {return tokenResult;}
+    if (!isAuthFailure(/** @type {{statusCode?: number}} */ (tokenResult)) || attempt === maxAttempts || typeof promptFn !== 'function') {
       return tokenResult;
     }
 
@@ -550,6 +605,11 @@ async function createTokenWithRetries(setup, user, initialPassword, options = {}
   return { ok: false, error: `token creation failed for ${user}` };
 }
 
+/**
+ * @param {string} [rootDir]
+ * @param {{promptFn?: Function, log?: Function, users?: string[]}} [options]
+ * @returns {Promise<{baseUrl: string, repo: string, ownerLogin: string, ownerPassword: string, agentPasswords: Array<{user: string, password: string}>, agentUsers: string[]}>}
+ */
 async function collectSetupAnswers(rootDir = process.cwd(), options = {}) {
   const {
     promptFn = promptLine,
@@ -568,7 +628,7 @@ async function collectSetupAnswers(rootDir = process.cwd(), options = {}) {
   const ownerLogin = (await promptFn(`Forgejo login with repo-create access [${defaultOwnerLogin}]: `)) || defaultOwnerLogin;
   const ownerPassword = await promptFn(passwordPrompt(ownerLogin), PASSWORD_PROMPT_OPTIONS);
   const userList = (await promptFn(`Agent Forgejo users [${defaultUsers}]: `)) || defaultUsers;
-  const agentUsers = unique(userList.split(',').map(value => value.trim()).filter(Boolean));
+  const agentUsers = unique(userList.split(',').map(/** @param {string} value */ value => value.trim()).filter(Boolean));
   const agentPasswords = [];
 
   for (const user of agentUsers) {
@@ -588,6 +648,11 @@ async function collectSetupAnswers(rootDir = process.cwd(), options = {}) {
   };
 }
 
+/**
+ * @param {string} [rootDir]
+ * @param {{promptFn?: Function, log?: Function, users?: string[], loadWorkflowConfigFn?: Function, detectPrimaryBranchDefaultFn?: Function}} [options]
+ * @returns {Promise<{productName: string, ownerLogin: string, baseUrl: string, reviewRepo: string, reviewRemote: string, bootstrapReview: boolean, ownerPassword: string, agentPasswords: Array<{user: string, password: string}>, agentUsers: string[], tasksProvider: string, tasksStorage: string, missionsBaseDir: string, branchPrefix: string, primaryBranch: string, worktreePattern: string, verificationCommand: string, verificationDefaultArea: string}>}
+ */
 async function collectWizardAnswers(rootDir = process.cwd(), options = {}) {
   const {
     promptFn = promptLine,
@@ -668,7 +733,7 @@ async function collectWizardAnswers(rootDir = process.cwd(), options = {}) {
     log(fmt.status('INFO', 'Forgejo bootstrap is enabled. Hidden password prompts are next: first for the repo-creating login, then once per listed agent user.'));
     ownerPassword = await promptFn(passwordPrompt(ownerLogin), PASSWORD_PROMPT_OPTIONS);
     const userList = (await promptFn(`Agent Forgejo users [${defaultUsers}]: `)) || defaultUsers;
-    agentUsers = unique(userList.split(',').map(value => value.trim()).filter(Boolean));
+    agentUsers = unique(userList.split(',').map(/** @param {string} value */ value => value.trim()).filter(Boolean));
     for (const user of agentUsers) {
       const password = await promptFn(passwordPrompt(user, { allowBlank: true }), PASSWORD_PROMPT_OPTIONS);
       if (password) {
@@ -677,7 +742,7 @@ async function collectWizardAnswers(rootDir = process.cwd(), options = {}) {
     }
   }
 
-  return {
+  return /** @type {{productName: string, ownerLogin: string, baseUrl: string, reviewRepo: string, reviewRemote: string, bootstrapReview: boolean, ownerPassword: string, agentPasswords: Array<{user: string, password: string}>, agentUsers: string[], tasksProvider: string, tasksStorage: string, missionsBaseDir: string, branchPrefix: string, primaryBranch: string, worktreePattern: string, verificationCommand: string, verificationDefaultArea: string}} */ ({
     productName,
     ownerLogin,
     baseUrl,
@@ -688,9 +753,10 @@ async function collectWizardAnswers(rootDir = process.cwd(), options = {}) {
     agentPasswords,
     agentUsers,
     ...defaults,
-  };
+  });
 }
 
+/** @param {string} user @param {string} token @param {string} [forgejoHome] @returns {string} */
 function writeToken(user, token, forgejoHome = resolveForgejoHome()) {
   ensureTokenDir(forgejoHome);
   const file = tokenFilePath(user, forgejoHome);
@@ -706,13 +772,22 @@ function writeToken(user, token, forgejoHome = resolveForgejoHome()) {
  * @param {string} baseUrl - Forgejo base URL
  * @param {string} repoSlug - Repository slug for token naming
  * @param {string} ownerToken - Owner's Forgejo PAT
- * @param {Array} agentPasswords - Array of {user, password} to create tokens for
- * @param {object} repoInfo - Parsed repo slug {owner, repo}
- * @param {object} options - Injected dependencies
- * @returns {{ ok: boolean, createdTokens: Array, warnings?: Array }}
+  * @param {Array<{user: string, password: string}>} agentPasswords - Array of {user, password} to create tokens for
+  * @param {{owner: string, repo: string}} repoInfo - Parsed repo slug {owner, repo}
+  * @param {{requestFn?: Function, writeTokenFn?: Function, buildTokenNameFn?: Function, forgejoHome?: string}} options - Injected dependencies
+  * @returns {{ ok: boolean, createdTokens: Array<{user: string, path: string}>, warnings?: Array<{user: string, error: string, response?: any}>, error?: string }}
+  */
+/**
+ * @param {string} baseUrl
+ * @param {string} repoSlug
+ * @param {string} ownerToken
+ * @param {Array<{user: string, password: string}>} agentPasswords
+ * @param {{owner: string, repo: string}} repoInfo
+ * @param {{requestFn?: Function, writeTokenFn?: Function, buildTokenNameFn?: Function, forgejoHome?: string}} [options]
+ * @returns {{ok: boolean, createdTokens: Array<{user: string, path: string}>, warnings?: Array<{user: string, error: string, response?: any}>, error?: string}}
  */
 function tokenCreateViaOwnerToken(baseUrl, repoSlug, ownerToken, agentPasswords, repoInfo, options = {}) {
-  const { requestFn = apiRequest, writeTokenFn, buildTokenNameFn = buildTokenName, log = fmt.log.info, forgejoHome: injectedForgejoHome } = options;
+  const { requestFn = apiRequest, writeTokenFn = writeToken, buildTokenNameFn = buildTokenName, forgejoHome: injectedForgejoHome } = options;
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
   const forgejoHome = typeof injectedForgejoHome === 'string' ? injectedForgejoHome : resolveForgejoHome();
 
@@ -757,6 +832,12 @@ function tokenCreateViaOwnerToken(baseUrl, repoSlug, ownerToken, agentPasswords,
   return { ok: true, createdTokens, warnings };
 }
 
+/**
+ * @param {string} rootDir
+ * @param {{baseUrl: string, repo: string, ownerLogin: string, ownerPassword: string, agentPasswords: Array<{user: string, password: string}>, agentUsers?: string[]}} setup
+ * @param {{log?: Function, promptFn?: Function, requestFn?: Function, maxPasswordAttempts?: number, interactive?: boolean, forgejoHome?: string}} [options]
+ * @returns {Promise<{ok: boolean, warnings?: Array<{user: string, error: string, response?: any}>, createdTokens?: Array<{user: string, path: string}>, error?: string, response?: any}>}
+ */
 async function bootstrapReviewSurface(rootDir = process.cwd(), setup, options = {}) {
   const {
     log = fmt.log.info,
@@ -781,7 +862,7 @@ async function bootstrapReviewSurface(rootDir = process.cwd(), setup, options =
     // Original interactive path: prompt for owner password, create tokens for all users
     const ownerTokenResult = await createTokenWithRetries({
       ...setup,
-      baseUrl,
+      baseUrl: /** @type {string} */ (baseUrl),
     }, setup.ownerLogin, setup.ownerPassword, {
       allowBlank: false,
       log,
@@ -789,24 +870,27 @@ async function bootstrapReviewSurface(rootDir = process.cwd(), setup, options =
       maxAttempts: maxPasswordAttempts,
       requestFn,
     });
-    if (!ownerTokenResult.ok) return ownerTokenResult;
+    if (!ownerTokenResult.ok) {return ownerTokenResult;}
+    const ownerToken = /** @type {string} */ (ownerTokenResult.token);
 
-    const ownerTokenPath = writeToken(setup.ownerLogin, ownerTokenResult.token, forgejoHome);
-    const repoResult = ensureRepo(baseUrl, setup.repo, setup.ownerLogin, ownerTokenResult.token, requestFn);
-    if (!repoResult.ok) return repoResult;
+    const ownerTokenPath = writeToken(setup.ownerLogin, ownerToken, forgejoHome);
+    // @ts-expect-error repo may be undefined
+    const repoResult = ensureRepo(baseUrl, setup.repo, setup.ownerLogin, ownerToken, requestFn);
+    if (!repoResult.ok) {return repoResult;}
 
-    const collaboratorResult = ensureRepoCollaborators(baseUrl, setup.repo, ownerTokenResult.token, collaboratorUsers, 'write', requestFn);
-    if (!collaboratorResult.ok) return collaboratorResult;
+    // @ts-expect-error repo may be undefined
+    const collaboratorResult = ensureRepoCollaborators(baseUrl, setup.repo, ownerToken, collaboratorUsers, 'write', requestFn);
+    if (!collaboratorResult.ok) {return collaboratorResult;}
     if (collaboratorResult.created.length > 0) {
-      log(fmt.status('PASS', `Granted write access on ${setup.repo} to ${collaboratorResult.created.join(', ')}`));
+      log(fmt.status('PASS', `Granted write access on ${setup.repo || ''} to ${collaboratorResult.created.join(', ')}`));
     }
 
     const createdTokens = [{ user: setup.ownerLogin, path: ownerTokenPath }];
-    const warnings = [];
+    const warnings = /** @type {Array<{user: string, error: string, response?: any}>} */ ([]);
     for (const agent of setup.agentPasswords) {
       const tokenResult = await createTokenWithRetries({
         ...setup,
-        baseUrl,
+        baseUrl: /** @type {string} */ (baseUrl),
       }, agent.user, agent.password, {
         allowBlank: true,
         log,
@@ -817,21 +901,21 @@ async function bootstrapReviewSurface(rootDir = process.cwd(), setup, options =
       if (!tokenResult.ok) {
         warnings.push({
           user: agent.user,
-          error: tokenResult.error,
+          error: /** @type {string} */ (tokenResult.error),
           response: tokenResult.response,
         });
         continue;
       }
-      if (tokenResult.skipped) continue;
-      createdTokens.push({ user: agent.user, path: writeToken(agent.user, tokenResult.token, forgejoHome) });
+      if (tokenResult.skipped) {continue;}
+      createdTokens.push({ user: agent.user, path: writeToken(agent.user, /** @type {string} */ (tokenResult.token), forgejoHome) });
     }
 
     const remoteUrl = reviewRemoteUrl(rootDir);
     const remoteName = resolveReviewAdapter(rootDir).remote || 'review';
     const remoteResult = remoteUrl ? ensureReviewRemote(rootDir, remoteName, remoteUrl) : { ok: true, created: false, updated: false };
-    if (!remoteResult.ok) return remoteResult;
+    if (!remoteResult.ok) {return remoteResult;}
 
-    log(fmt.status('PASS', `Forgejo repo ${setup.repo} ${repoResult.created ? 'created' : 'already exists'}.`));
+  log(fmt.status('PASS', `Forgejo repo ${setup.repo} ${repoResult.created ? 'created' : 'already exists'}.`));
     for (const tokenInfo of createdTokens) {
       log(fmt.status('PASS', `Wrote Forgejo token for ${tokenInfo.user} to ${tokenInfo.path}`));
     }
@@ -856,22 +940,25 @@ async function bootstrapReviewSurface(rootDir = process.cwd(), setup, options =
     ownerToken = fs.readFileSync(ownerTokenPath, 'utf8').trim();
   }
   if (!ownerToken) {
-    return { ok: false, error: `No owner token found for ${setup.ownerLogin} at ${ownerTokenPath}. A token file for an existing user (typically human) is required to bootstrap new agent tokens.` };
+    return { ok: false, error: `No owner token found for ${/** @type {string} */ (setup.ownerLogin)} at ${ownerTokenPath}. A token file for an existing user (typically human) is required to bootstrap new agent tokens.` };
   }
 
+  // @ts-expect-error repo may be undefined
   const repoResult = ensureRepo(baseUrl, setup.repo, setup.ownerLogin, ownerToken, requestFn);
-  if (!repoResult.ok) return repoResult;
+  if (!repoResult.ok) {return repoResult;}
 
+  // @ts-expect-error repo may be undefined
   const collaboratorResult = ensureRepoCollaborators(baseUrl, setup.repo, ownerToken, collaboratorUsers, 'write', requestFn);
-  if (!collaboratorResult.ok) return collaboratorResult;
+  if (!collaboratorResult.ok) {return collaboratorResult;}
   if (collaboratorResult.created.length > 0) {
     log(fmt.status('PASS', `Granted write access on ${setup.repo} to ${collaboratorResult.created.join(', ')}`));
   }
 
+  // @ts-expect-error repo may be undefined
   const tokensResult = tokenCreateViaOwnerToken(baseUrl, setup.repo, ownerToken, setup.agentPasswords, repoInfo, { requestFn, writeTokenFn: writeToken, forgejoHome, log });
-  if (!tokensResult.ok) return tokensResult;
+  if (!tokensResult.ok) {return tokensResult;}
 
-  const { createdTokens, warnings } = tokensResult;
+  const { createdTokens, warnings = [] } = /** @type {{createdTokens: Array<{user: string, path: string}>, warnings: Array<{user: string, error: string, response?: any}>}} */ (tokensResult);
   for (const tokenInfo of createdTokens) {
     log(fmt.status('PASS', `Wrote Forgejo token for ${tokenInfo.user} to ${tokenInfo.path}`));
   }
@@ -885,14 +972,19 @@ async function bootstrapReviewSurface(rootDir = process.cwd(), setup, options =
   const remoteUrl = reviewRemoteUrl(rootDir);
   const remoteName = resolveReviewAdapter(rootDir).remote || 'review';
   const remoteResult = remoteUrl ? ensureReviewRemote(rootDir, remoteName, remoteUrl) : { ok: true, created: false, updated: false };
-  if (!remoteResult.ok) return remoteResult;
+  if (!remoteResult.ok) {return remoteResult;}
 
-  log(fmt.status('PASS', `Forgejo repo ${setup.repo} ${repoResult.created ? 'created' : 'already exists'}.`));
+  log(fmt.status('PASS', `Forgejo repo ${/** @type {string} */ (setup.repo)} ${repoResult.created ? 'created' : 'already exists'}.`));
   log(fmt.status('PASS', `Review remote "${remoteName}" now points at ${remoteUrl}`));
 
   return { ok: true, warnings, createdTokens };
 }
 
+/**
+ * @param {any[]} _args
+ * @param {{rootDir?: string, log?: Function, error?: Function, exit?: Function, promptFn?: Function, forgejoHome?: string}} [options]
+ * @returns {Promise<void>}
+ */
 async function setupReview(_args, options = {}) {
   const rootDir = options.rootDir || process.cwd();
   const log = options.log || fmt.log.plain;
@@ -905,7 +997,7 @@ async function setupReview(_args, options = {}) {
     forgejoHome: resolveBootstrapForgejoHome(rootDir, options.forgejoHome),
   });
   if (!result.ok) {
-    error(fmt.status('FAIL', result.error));
+    error(fmt.status('FAIL', /** @type {string} */ (result.error || '')));
     if (result.response) {
       error(fmt.status('INFO', `Forgejo response: ${JSON.stringify(result.response)}`));
     }
@@ -914,8 +1006,9 @@ async function setupReview(_args, options = {}) {
   }
 }
 
+/** @param {string} rootDir @param {{verifyFn?: Function}} [options] @returns {Promise<{status: number}>} */
 async function runVerifyEnv(rootDir, options = {}) {
-  const verifyFn = options.verifyFn || ((cwd) => spawnSync('node', ['workflow', 'verify-env'], {
+  const verifyFn = options.verifyFn || /** @param {string} cwd @returns {{status: number}} */ ((/** @type {string} */ cwd) => spawnSync('node', ['workflow', 'verify-env'], {
     cwd,
     stdio: 'inherit',
     encoding: 'utf8',
@@ -923,6 +1016,7 @@ async function runVerifyEnv(rootDir, options = {}) {
   return verifyFn(rootDir);
 }
 
+/** @param {string} rootDir @param {{log?: Function}} [options] @returns {{productName: string, reviewProvider: string, tasksProvider: string, tasksStorage: string, missionsBaseDir: string, branchPrefix: string, primaryBranch: string, worktreePattern: string, verificationCommand: string, verificationDefaultArea: string, bootstrapReview: boolean, ownerLogin?: string, baseUrl?: string, reviewRepo?: string, reviewRemote?: string, ownerPassword?: string, agentPasswords?: Array<{user: string, password: string}>, agentUsers?: string[]}} */
 function buildNonInteractiveAnswers(rootDir, options = {}) {
   const log = options.log || fmt.log.plain;
   const env = process.env;
@@ -970,6 +1064,11 @@ function buildNonInteractiveAnswers(rootDir, options = {}) {
   return answers;
 }
 
+/**
+ * @param {any[]} _args
+ * @param {{rootDir?: string, log?: Function, error?: Function, exit?: Function, promptFn?: Function, forgejoHome?: string}} [options]
+ * @returns {Promise<void>}
+ */
 async function setupWizard(_args, options = {}) {
   const rootDir = options.rootDir || process.cwd();
   const log = options.log || fmt.log.plain;
@@ -979,8 +1078,9 @@ async function setupWizard(_args, options = {}) {
   const forgejoHome = resolveBootstrapForgejoHome(rootDir, options.forgejoHome);
 
   const nonInteractive = (_args && _args.includes('--non-interactive')) || process.env.WORKFLOW_SETUP_NON_INTERACTIVE === '1';
+  /** @type {{productName: string, ownerLogin: string, baseUrl: string, reviewRepo: string, reviewRemote: string, bootstrapReview: boolean, ownerPassword: string, agentPasswords: Array<{user: string, password: string}>, agentUsers: string[], tasksProvider: string, tasksStorage: string, missionsBaseDir: string, branchPrefix: string, primaryBranch: string, worktreePattern: string, verificationCommand: string, verificationDefaultArea: string}} */
   const answers = nonInteractive
-    ? buildNonInteractiveAnswers(rootDir, { log })
+    ? /** @type {{productName: string, ownerLogin: string, baseUrl: string, reviewRepo: string, reviewRemote: string, bootstrapReview: boolean, ownerPassword: string, agentPasswords: Array<{user: string, password: string}>, agentUsers: string[], tasksProvider: string, tasksStorage: string, missionsBaseDir: string, branchPrefix: string, primaryBranch: string, worktreePattern: string, verificationCommand: string, verificationDefaultArea: string}} */ (buildNonInteractiveAnswers(rootDir, { log }))
     : await collectWizardAnswers(rootDir, { ...options, promptFn, log });
   const configPath = writeWorkflowConfig(rootDir, buildWorkflowConfig(answers));
   log(fmt.status('PASS', `Wrote ${configPath}`));
@@ -1009,7 +1109,7 @@ async function setupWizard(_args, options = {}) {
       forgejoHome,
     });
     if (!result.ok) {
-      error(fmt.status('FAIL', result.error));
+      error(fmt.status('FAIL', /** @type {string} */ (result.error || '')));
       if (result.response) {
         error(fmt.status('INFO', `Forgejo response: ${JSON.stringify(result.response)}`));
       }
@@ -1020,7 +1120,7 @@ async function setupWizard(_args, options = {}) {
     log(fmt.status('INFO', 'Skipped Forgejo bootstrap. You can run `px setup-review` later if needed.'));
   }
 
-  const verifyResult = await runVerifyEnv(rootDir, options);
+  const verifyResult = await runVerifyEnv(rootDir, /** @type {{verifyFn?: Function}} */ (options));
   if (verifyResult && typeof verifyResult.status === 'number' && verifyResult.status !== 0) {
     exit(verifyResult.status);
   }