switchback-core 2026.11.3 → 2026.11.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "switchback-core",
3
- "version": "2026.11.3",
3
+ "version": "2026.11.5",
4
4
  "type": "module",
5
5
  "description": "Host-agnostic core for switchback: fallback routing, error classification ports, block state and configuration.",
6
6
  "license": "MIT",
package/src/config.ts CHANGED
@@ -118,6 +118,36 @@ export const SWITCHBACK_CONFIG_DIR_ENV = "SWITCHBACK_CONFIG_DIR";
118
118
  /** Env override naming the shared switchback state directory outright. */
119
119
  export const SWITCHBACK_DIR_ENV = "SWITCHBACK_DIR";
120
120
 
121
+ /** Env override for the `debug:` flag: any value but 0/false/off/no enables it. */
122
+ export const SWITCHBACK_DEBUG_ENV = "SWITCHBACK_DEBUG";
123
+
124
+ /**
125
+ * Read an environment override for the config's `debug:` flag.
126
+ *
127
+ * An empty or absent value means "no override" (`undefined`) so the config
128
+ * decides; `0`/`false`/`off`/`no` (any case) disable, anything else enables.
129
+ * Shared by both hosts: the documented `SWITCHBACK_DEBUG=1` override is a
130
+ * property of the config surface, not of one adapter.
131
+ */
132
+ export function debugFlag(value: string | undefined): boolean | undefined {
133
+ const v = value?.trim().toLowerCase();
134
+ if (v === undefined || v === "") return undefined;
135
+ return !(v === "0" || v === "false" || v === "off" || v === "no");
136
+ }
137
+
138
+ /**
139
+ * The effective diagnostics switch: `SWITCHBACK_DEBUG` when it says anything,
140
+ * otherwise the config's `debug:`, otherwise off. Both hosts resolve it here so
141
+ * the env override cannot drift between them (pi shipped it, OpenCode silently
142
+ * ignored it while the docs promised both).
143
+ */
144
+ export function resolveDebug(
145
+ configured: boolean | undefined,
146
+ env: Record<string, string | undefined> = process.env,
147
+ ): boolean {
148
+ return debugFlag(env[SWITCHBACK_DEBUG_ENV]) ?? configured ?? false;
149
+ }
150
+
121
151
  /**
122
152
  * The shared switchback state directory: blocks.json, crashes.json,
123
153
  * pin.json, secrets.json. Runtime files live here so they are account-scoped,
@@ -419,28 +449,40 @@ const SECRETS_PREFIX = "secret:";
419
449
  /**
420
450
  * Resolve a `secret:<ref>` apiKey value against a secret store. Anything else
421
451
  * (the literal string `ollama`, a real token, etc.) passes through unchanged.
422
- * A missing reference throws `SecretsError` (re-raised by the caller) - a secret
423
- * reference that does not resolve is a user error, not a silent default.
452
+ *
453
+ * An unresolvable reference never fails the load: it becomes a warning and the
454
+ * key is dropped (`apiKey` resolves to `undefined`), so the entry keeps its
455
+ * `baseUrl` and every other decision model stays usable. One unavailable
456
+ * credential must not disable classification for the whole config - a host
457
+ * may have no store at all (OpenCode resolves refs against the environment),
458
+ * and a single unset variable is a routine state, not a broken file. The host
459
+ * reports the warning through its own notify channel.
424
460
  */
425
461
  export function resolveSecretApiKey(
426
462
  apiKey: string | undefined,
427
463
  secrets: { get(name: string): string | undefined } | undefined,
464
+ warnings: string[] = [],
465
+ where = "<config>",
428
466
  ): string | undefined {
429
467
  if (apiKey === undefined) return undefined;
430
468
  if (!apiKey.startsWith(SECRETS_PREFIX)) return apiKey;
431
- if (secrets === undefined) {
432
- throw new ConfigError(
433
- `apiKey starts with "${SECRETS_PREFIX}" but no secret store was provided - pass one to loadConfig() or define the key in the secret store first.`,
434
- "<config>",
435
- );
436
- }
437
469
  const name = apiKey.slice(SECRETS_PREFIX.length);
438
470
  if (name.length === 0) {
439
- throw new ConfigError(`apiKey "${SECRETS_PREFIX}" is missing a name`, "<config>");
471
+ warnings.push(`${where}.apiKey "${SECRETS_PREFIX}" is missing a name - the key is ignored`);
472
+ return undefined;
473
+ }
474
+ if (secrets === undefined) {
475
+ warnings.push(
476
+ `${where}.apiKey "${apiKey}" cannot resolve (this host provides no secret store) - the key is ignored`,
477
+ );
478
+ return undefined;
440
479
  }
441
480
  const value = secrets.get(name);
442
481
  if (value === undefined) {
443
- throw new ConfigError(`apiKey "${apiKey}" does not resolve (secret "${name}" is not in the store)`, "<config>");
482
+ warnings.push(
483
+ `${where}.apiKey "${apiKey}" does not resolve (secret "${name}" is not in the store) - the key is ignored`,
484
+ );
485
+ return undefined;
444
486
  }
445
487
  return value;
446
488
  }
@@ -453,13 +495,19 @@ export function resolveSecretApiKey(
453
495
  function resolveFile(
454
496
  file: SwitchbackFileConfig,
455
497
  secrets: { get(name: string): string | undefined } | undefined = undefined,
498
+ warnings: string[] = [],
456
499
  ): ResolvedSwitchbackFileConfig {
457
500
  const resolvedDecisionProviders: Record<string, DecisionProviderConfig> | undefined =
458
501
  file.decisionProviders === undefined
459
502
  ? undefined
460
503
  : Object.fromEntries(
461
504
  Object.entries(file.decisionProviders).map(([provider, entry]) => {
462
- const apiKey = resolveSecretApiKey(entry.apiKey, secrets);
505
+ const apiKey = resolveSecretApiKey(
506
+ entry.apiKey,
507
+ secrets,
508
+ warnings,
509
+ `decisionProviders.${provider}`,
510
+ );
463
511
  const descriptor: DecisionProviderConfig = {
464
512
  ...(entry.baseUrl !== undefined ? { baseUrl: entry.baseUrl } : {}),
465
513
  ...(apiKey !== undefined ? { apiKey } : {}),
@@ -473,7 +521,7 @@ function resolveFile(
473
521
  : Object.fromEntries(
474
522
  Object.entries(file.decisionModels).map(([address, entry]) => {
475
523
  const { provider, id } = splitAddress(address, `decisionModels.${address}`);
476
- const apiKey = resolveSecretApiKey(entry.apiKey, secrets);
524
+ const apiKey = resolveSecretApiKey(entry.apiKey, secrets, warnings, `decisionModels.${address}`);
477
525
  const descriptor: DecisionModelConfig = {
478
526
  provider,
479
527
  id,
@@ -707,7 +755,7 @@ export function loadConfig(
707
755
  : base !== undefined
708
756
  ? resolve(path)
709
757
  : resolve(configOverlayPath(host!));
710
- return { config: resolveFile(merged, secrets), source, warnings };
758
+ return { config: resolveFile(merged, secrets, warnings), source, warnings };
711
759
  }
712
760
 
713
761
  /**
package/src/index.ts CHANGED
@@ -93,6 +93,9 @@ export {
93
93
  switchbackStateDir,
94
94
  resolveDecisionModel,
95
95
  resolveSecretApiKey,
96
+ resolveDebug,
97
+ debugFlag,
98
+ SWITCHBACK_DEBUG_ENV,
96
99
  validateFileConfig,
97
100
  createConfigWarningReporter,
98
101
  } from "./config.ts";