feat(config): read ~/.testsprite/config for persistent defaults (endpoint_url, output, project_id)

Author: Andy00L

src/commands/test.ts

@@ -65,7 +65,7 @@ import { assertNotLocal } from '../lib/target-url.js';
 import { createTicker } from '../lib/ticker.js';
 import { RateThrottle } from '../lib/rate-throttle.js';
 import { resolvePortalBase, resolvePortalUrl } from '../lib/facade.js';
-import { loadConfig } from '../lib/config.js';
+import { loadConfig, readConfigFileSettings } from '../lib/config.js';
 
 /**
  * `details` debug block per the CLI OpenAPI `Test` schema
@@ -444,7 +444,7 @@ export async function runList(opts: ListOptions, deps: TestDeps = {}): Promise<P
   // (exit 3) when the caller also lacks a configured key. Order matters
   // for the CLI error spec §2 — bad input is a caller bug, not an auth
   // gate.
-  requireProjectId(opts.projectId);
+  opts.projectId = requireProjectId(opts.projectId, opts.profile);
 
   const paginationFlags: PaginationFlags = validatePaginationFlags({
     pageSize: opts.pageSize,
@@ -671,7 +671,7 @@ export async function runCreate(
   assertChainedRunKeyFits(opts.run, opts.idempotencyKey);
   // Validate inputs before touching credentials or fs — matches the
   // M2 read commands' "input gates first, then auth, then I/O" ordering.
-  requireProjectId(opts.projectId);
+  opts.projectId = requireProjectId(opts.projectId, opts.profile);
   requireNonEmpty('name', opts.name);
   // P1-3: client-side length checks matching server limits (name ≤200,
   // description ≤2000) so the user gets instant, actionable errors instead
@@ -5097,7 +5097,7 @@ export async function runTestRunAll(
   deps: TestDeps = {},
 ): Promise<BatchRunFreshResponse | undefined> {
   assertIdempotencyKey(opts.idempotencyKey);
-  requireProjectId(opts.projectId);
+  opts.projectId = requireProjectId(opts.projectId, opts.profile);
   if (
     !Number.isInteger(opts.maxConcurrency) ||
     opts.maxConcurrency < 1 ||
@@ -7772,10 +7772,25 @@ interface StepsFlagOpts {
   runId?: string;
 }
 
-function requireProjectId(projectId: string): void {
-  if (typeof projectId !== 'string' || projectId.length === 0) {
-    throw localValidationError('project', 'is required');
+/**
+ * Resolve the effective project id: the `--project` flag when set, otherwise
+ * the `project_id` persisted in the settings config file
+ * (`~/.testsprite/config`), so a repo/agent can pin the project once instead
+ * of repeating it per command. Throws VALIDATION_ERROR (exit 5) when neither
+ * is present.
+ */
+function requireProjectId(projectId: string | undefined, profile = 'default'): string {
+  const resolved =
+    typeof projectId === 'string' && projectId.length > 0
+      ? projectId
+      : readConfigFileSettings(profile).projectId;
+  if (typeof resolved !== 'string' || resolved.length === 0) {
+    throw localValidationError(
+      'project',
+      'is required (pass --project or set project_id in ~/.testsprite/config)',
+    );
   }
+  return resolved;
 }
 
 /**

src/index.ts

@@ -10,6 +10,7 @@ import {
 import { createProjectCommand } from './commands/project.js';
 import { createTestCommand } from './commands/test.js';
 import { createUsageCommand } from './commands/usage.js';
+import { readConfigFileSettings } from './lib/config.js';
 import { ApiError, CLIError, RequestTimeoutError } from './lib/errors.js';
 import { Output, isOutputMode } from './lib/output.js';
 import { renderCommanderError, rephraseUnknownOption } from './lib/render-error.js';
@@ -18,6 +19,17 @@ import { VERSION } from './version.js';
 
 const program = new Command();
 
+/**
+ * Default for the global `--output` flag: the `output` key of the profile's
+ * section in `~/.testsprite/config` when present. Flag values and the
+ * env-selected profile still win; an invalid or absent value falls back to
+ * 'text' (the historical default).
+ */
+function configFileOutputDefault(): string {
+  const settings = readConfigFileSettings(process.env.TESTSPRITE_PROFILE ?? 'default');
+  return isOutputMode(settings.output) ? settings.output : 'text';
+}
+
 // exitOverride() causes Commander to throw CommanderError instead of calling
 // process.exit() directly, giving our catch block a chance to remap error
 // exit codes (e.g. missing-argument → exit 5 per taxonomy).
@@ -27,7 +39,7 @@ program
   .name('testsprite')
   .description('Official TestSprite command-line interface')
   .version(VERSION)
-  .option('--output <mode>', 'Output format (json|text)', 'text')
+  .option('--output <mode>', 'Output format (json|text)', configFileOutputDefault())
   .option('--profile <name>', 'Configuration profile to use')
   .option('--endpoint-url <url>', 'Override the API endpoint host')
   .option(

src/lib/config.test.ts

@@ -1,8 +1,8 @@
-import { mkdtempSync } from 'node:fs';
+import { mkdtempSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { defaultConfigPath, loadConfig } from './config.js';
+import { defaultConfigPath, loadConfig, readConfigFileSettings } from './config.js';
 import { writeProfile } from './credentials.js';
 
 let tmpRoot: string;
@@ -88,3 +88,53 @@ describe('defaultConfigPath', () => {
     expect(defaultConfigPath()).toBe(join(homedir(), '.testsprite', 'config'));
   });
 });
+
+describe('readConfigFileSettings + the config-file layer of loadConfig', () => {
+  function writeConfigFile(content: string): string {
+    const path = join(mkdtempSync(join(tmpdir(), 'testsprite-config-')), 'config');
+    writeFileSync(path, content, 'utf8');
+    return path;
+  }
+
+  it('reads endpoint_url/output/project_id from the profile section', () => {
+    const path = writeConfigFile(
+      '[default]\nendpoint_url = https://selfhosted.example.com\noutput = json\nproject_id = project_cfg\n',
+    );
+    expect(readConfigFileSettings('default', { path })).toEqual({
+      endpointUrl: 'https://selfhosted.example.com',
+      output: 'json',
+      projectId: 'project_cfg',
+    });
+    // A different profile section is not leaked into.
+    expect(readConfigFileSettings('other', { path })).toEqual({});
+  });
+
+  it('missing file and unknown keys are non-fatal', () => {
+    expect(readConfigFileSettings('default', { path: '/nope/definitely/missing' })).toEqual({});
+    const path = writeConfigFile('[default]\nmystery_key = x\n');
+    expect(readConfigFileSettings('default', { path })).toEqual({});
+  });
+
+  it('resolves the path from TESTSPRITE_CONFIG_FILE when no explicit path is given', () => {
+    const path = writeConfigFile('[default]\nproject_id = project_from_env_path\n');
+    const settings = readConfigFileSettings('default', {
+      env: { TESTSPRITE_CONFIG_FILE: path },
+    });
+    expect(settings.projectId).toBe('project_from_env_path');
+  });
+
+  it('loadConfig: config-file endpoint_url sits above the built-in default and below env', () => {
+    const path = writeConfigFile('[default]\nendpoint_url = https://cfg.example.com\n');
+    const missingCreds = join(mkdtempSync(join(tmpdir(), 'testsprite-creds-')), 'credentials');
+    // Only the config file supplies a URL -> it wins over the built-in default.
+    const fromConfig = loadConfig({ env: {}, credentialsPath: missingCreds, configPath: path });
+    expect(fromConfig.apiUrl).toBe('https://cfg.example.com');
+    // Env still outranks the config file.
+    const fromEnv = loadConfig({
+      env: { TESTSPRITE_API_URL: 'https://env.example.com' },
+      credentialsPath: missingCreds,
+      configPath: path,
+    });
+    expect(fromEnv.apiUrl).toBe('https://env.example.com');
+  });
+});

src/lib/config.ts

@@ -1,6 +1,12 @@
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_PROFILE, defaultCredentialsPath, readProfile } from './credentials.js';
+import {
+  DEFAULT_PROFILE,
+  defaultCredentialsPath,
+  parseIniFile,
+  readProfile,
+} from './credentials.js';
 
 export interface Config {
   apiUrl: string;
@@ -13,6 +19,8 @@ export interface LoadConfigOptions {
   endpointUrl?: string;
   env?: NodeJS.ProcessEnv;
   credentialsPath?: string;
+  /** Settings file override; defaults to `TESTSPRITE_CONFIG_FILE` or `~/.testsprite/config`. */
+  configPath?: string;
 }
 
 const DEFAULT_API_URL = 'https://api.testsprite.com';
@@ -21,25 +29,87 @@ export function defaultConfigPath(): string {
   return join(homedir(), '.testsprite', 'config');
 }
 
+/**
+ * Non-credential defaults a user can persist in `~/.testsprite/config`
+ * (aws-cli's credentials-vs-config split: the key lives in `credentials`,
+ * settings live here). INI sections are profile names, mirroring the
+ * credentials file.
+ */
+export interface ConfigFileSettings {
+  endpointUrl?: string;
+  output?: string;
+  projectId?: string;
+}
+
+/** INI key -> settings field. sourceRef: DOCUMENTATION.md configuration table. */
+const CONFIG_KEY_TO_FIELD: Record<string, keyof ConfigFileSettings> = {
+  endpoint_url: 'endpointUrl',
+  output: 'output',
+  project_id: 'projectId',
+};
+
+export interface ReadConfigFileOptions {
+  env?: NodeJS.ProcessEnv;
+  path?: string;
+}
+
+/**
+ * Read the `[profile]` section of the settings config file. Missing or
+ * unreadable file (or section) yields `{}` so the cascade falls through to
+ * built-in defaults; the file is optional by design. Reuses the hardened INI
+ * parser the credentials file uses (null-prototype + proto-key guards).
+ */
+export function readConfigFileSettings(
+  profile: string,
+  options: ReadConfigFileOptions = {},
+): ConfigFileSettings {
+  const env = options.env ?? process.env;
+  const path = options.path ?? env.TESTSPRITE_CONFIG_FILE ?? defaultConfigPath();
+  let content: string;
+  try {
+    if (!existsSync(path)) return {};
+    content = readFileSync(path, 'utf-8');
+  } catch {
+    // Unreadable settings file: settings are optional, never fatal.
+    return {};
+  }
+  const section = parseIniFile(content)[profile];
+  if (!section) return {};
+  const settings: ConfigFileSettings = {};
+  for (const [rawKey, field] of Object.entries(CONFIG_KEY_TO_FIELD)) {
+    const value = section[rawKey];
+    if (typeof value === 'string' && value.length > 0) settings[field] = value;
+  }
+  return settings;
+}
+
 /**
  * Resolves the active profile name and its (apiUrl, apiKey) pair.
  *
  * Resolution order, highest precedence first:
  *   profile name:  options.profile  > env.TESTSPRITE_PROFILE > "default"
  *   apiKey:        env.TESTSPRITE_API_KEY > credentials file profile entry
- *   apiUrl:        options.endpointUrl > env.TESTSPRITE_API_URL > credentials file > built-in default
+ *   apiUrl:        options.endpointUrl > env.TESTSPRITE_API_URL > credentials file
+ *                  > config file `endpoint_url` > built-in default
  *
  * Env wins over the credentials file so CI / scripted callers can run without touching
- * the user's ~/.testsprite/credentials.
+ * the user's ~/.testsprite/credentials. The config file sits just above the built-in
+ * default: it is where a user persists "this machine talks to this endpoint" once.
  */
 export function loadConfig(options: LoadConfigOptions = {}): Config {
   const env = options.env ?? process.env;
   const profile = options.profile ?? env.TESTSPRITE_PROFILE ?? DEFAULT_PROFILE;
   const credentialsPath = options.credentialsPath ?? defaultCredentialsPath();
   const fileEntry = readProfile(profile, { path: credentialsPath });
+  const settings = readConfigFileSettings(profile, { env, path: options.configPath });
 
   return {
-    apiUrl: options.endpointUrl ?? env.TESTSPRITE_API_URL ?? fileEntry?.apiUrl ?? DEFAULT_API_URL,
+    apiUrl:
+      options.endpointUrl ??
+      env.TESTSPRITE_API_URL ??
+      fileEntry?.apiUrl ??
+      settings.endpointUrl ??
+      DEFAULT_API_URL,
     apiKey: env.TESTSPRITE_API_KEY ?? fileEntry?.apiKey,
     profile,
   };

src/lib/credentials.ts

@@ -71,20 +71,39 @@ const FIELD_TO_FILE_KEY: Record<keyof ProfileEntry, string> = {
   apiUrl: 'api_url',
 };
 
-export function parseCredentials(content: string): CredentialsFile {
-  const result: CredentialsFile = {};
-  let currentEntry: ProfileEntry | null = null;
+/**
+ * Generic hardened INI walk shared by the credentials file and the settings
+ * config file (`~/.testsprite/config`). Returns every `[section]`'s raw
+ * key=value pairs; callers map the keys they understand.
+ */
+export function parseIniFile(content: string): Record<string, Record<string, string>> {
+  // Null-prototype accumulator so a `[__proto__]` / `[constructor]` section
+  // cannot alias a shared prototype object and let the following key=value
+  // lines pollute every object in the process (prototype-pollution hardening).
+  // The result is copied into a plain object on return for caller back-compat.
+  const result: Record<string, Record<string, string>> = Object.create(null);
+  let currentEntry: Record<string, string> | null = null;
   for (const rawLine of content.split('\n')) {
     const line = rawLine.trim();
     if (line === '' || line.startsWith('#') || line.startsWith(';')) continue;
     const sectionMatch = /^\[([^\]]+)\]$/.exec(line);
     if (sectionMatch) {
       const sectionName = sectionMatch[1]!.trim();
+      // Defense in depth alongside the null-prototype accumulator: never treat a
+      // prototype-polluting key as a profile section. Skip its key=value lines.
+      if (
+        sectionName === '__proto__' ||
+        sectionName === 'constructor' ||
+        sectionName === 'prototype'
+      ) {
+        currentEntry = null;
+        continue;
+      }
       const existing = result[sectionName];
       if (existing) {
         currentEntry = existing;
       } else {
-        const newEntry: ProfileEntry = {};
+        const newEntry: Record<string, string> = Object.create(null) as Record<string, string>;
         result[sectionName] = newEntry;
         currentEntry = newEntry;
       }
@@ -95,8 +114,27 @@ export function parseCredentials(content: string): CredentialsFile {
     if (eqIndex < 0) continue;
     const rawKey = line.slice(0, eqIndex).trim();
     const rawValue = line.slice(eqIndex + 1).trim();
-    const field = FILE_KEY_TO_FIELD[rawKey];
-    if (field) currentEntry[field] = rawValue;
+    // Same guard for keys: `__proto__ = x` must never become a property write
+    // on a shared prototype when a caller copies the section into a plain map.
+    if (rawKey === '__proto__' || rawKey === 'constructor' || rawKey === 'prototype') continue;
+    currentEntry[rawKey] = rawValue;
+  }
+  // Return plain objects so callers (and test matchers) see normal prototypes.
+  const plain: Record<string, Record<string, string>> = {};
+  for (const [name, entry] of Object.entries(result)) plain[name] = { ...entry };
+  return plain;
+}
+
+export function parseCredentials(content: string): CredentialsFile {
+  const sections = parseIniFile(content);
+  const result: CredentialsFile = {};
+  for (const [name, keyValues] of Object.entries(sections)) {
+    const entry: ProfileEntry = {};
+    for (const [rawKey, rawValue] of Object.entries(keyValues)) {
+      const field = FILE_KEY_TO_FIELD[rawKey];
+      if (field) entry[field] = rawValue;
+    }
+    result[name] = entry;
   }
   return result;
 }