studiograph 1.3.48-next.13 → 1.3.48-next.130

package/dist/core/secrets/read-flip.js

@@ -0,0 +1,87 @@
+/**
+ * Read-flip helpers — Phase 6 of the secrets refactor.
+ *
+ * Call sites that historically read directly from `~/.studiograph/user.json`
+ * / `workspace.json` / `process.env.*` route through this module so the
+ * flip is uniform across the codebase.
+ *
+ * Contract: every helper here returns `undefined` when the resolver
+ * returns `unset` (or when the store hasn't been initialized yet —
+ * very early boot or test harness without a store). Callers MUST fall
+ * back to their pre-existing legacy read in that case. This is the
+ * transitional safety net documented in the plan: if the importer
+ * hasn't run yet (boot race, mis-provisioned redeploy), the resolver
+ * sees empty slots and we don't want to regress to "no value at all".
+ *
+ * When the resolver returns a value, callers MUST use it and skip the
+ * legacy read. The store is the source of truth in production.
+ *
+ * Why a thin wrapper rather than inlining `getSettingsResolver()?.resolve()`
+ * at every call site:
+ *   1. Single place to handle the "store not yet initialized" guard.
+ *   2. Single place to flip the implementation again in Phase 9 (when
+ *      legacy fallbacks are removed).
+ *   3. Concise call sites: `tryResolve('model.anthropic.api_key')` is
+ *      shorter than the resolver dance.
+ *
+ * Historical note: the `STUDIOGRAPH_NEW_STORE` env flag previously
+ * gated these helpers (returned undefined when off). The flag was
+ * removed once Phase 6 was proven stable in production — the store is
+ * now unconditional. The env var can still be set on Railway services
+ * for backwards-compat; it is silently ignored.
+ */
+import { getSettingsResolver, hasSecretStore } from './index.js';
+/**
+ * Try to resolve a value through the new store. Returns `undefined`
+ * when the flag is off OR the resolver returns unset. Callers handle
+ * `undefined` by falling back to their legacy reader.
+ *
+ * For non-secret values, this hits the `settings` table directly via
+ * the resolver's read path. The value type is whatever was JSON-stored,
+ * cast to T at the boundary.
+ *
+ * For secret values, this calls `unsafeGetForResolver` through the
+ * resolver — same access pattern as the legacy reader, except the
+ * value lands from an encrypted SQLite row rather than a 0o600 JSON
+ * file. The "unsafe" prefix on the underlying call is a marker for
+ * "value crosses the resolver boundary" — UI/API callers must use
+ * `describe()` instead and never touch this helper.
+ */
+export function tryResolve(key, ctx = {}) {
+    if (!hasSecretStore())
+        return undefined;
+    const resolver = getSettingsResolver();
+    if (!resolver)
+        return undefined;
+    try {
+        return resolver.resolve(key, ctx);
+    }
+    catch {
+        // Unknown key — registry didn't include it. Treat as "no value"
+        // and let the caller fall through. The resolver only throws when
+        // the registry lookup fails; that means the call site is passing
+        // a key name that isn't registered, which is a programmer error
+        // worth surfacing — but not by crashing a runtime read path.
+        return undefined;
+    }
+}
+/**
+ * Same shape but also returns the resolution source. Useful for
+ * surfaces that want to show a "shadowed by environment" banner in
+ * the UI without re-doing the lookup.
+ */
+export function tryResolveWithSource(key, ctx = {}) {
+    if (!hasSecretStore())
+        return undefined;
+    const resolver = getSettingsResolver();
+    if (!resolver)
+        return undefined;
+    try {
+        const r = resolver.resolveWithSource(key, ctx);
+        return { value: r.value, source: r.source };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=read-flip.js.map

package/dist/core/secrets/read-flip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-flip.js","sourceRoot":"","sources":["../../../src/core/secrets/read-flip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,MAAuB,EAAE;IAEzB,IAAI,CAAC,cAAc,EAAE;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IACvC,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,CAAI,GAAG,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;QAChE,iEAAiE;QACjE,iEAAiE;QACjE,gEAAgE;QAChE,6DAA6D;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,MAAuB,EAAE;IAEzB,IAAI,CAAC,cAAc,EAAE;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IACvC,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAI,GAAG,EAAE,GAAG,CAAC,CAAC;QAClD,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/core/secrets/registry.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Key Registry — single source of truth for every configurable key.
+ *
+ * Every consumer (resolver, importer, validator, redactor, audit logger,
+ * exporter, test suite) reads from this module. If a `process.env.<KEY>`
+ * appears in `src/`, it MUST be either listed under some entry's
+ * `envAliases` or covered by `SYSTEM_ALLOWLIST` / `OPERATIONAL_ALLOWLIST`.
+ * The registry-completeness test enforces this — orphans fail CI with
+ * their names printed.
+ *
+ * Adding a new env var? Two-step: pick the right classification, add the
+ * KeyDef here. The completeness test will keep you honest.
+ */
+import { type ZodType } from 'zod';
+import { type TestResult } from './probes/anthropic.js';
+export type Classification = 'bootstrap' | 'workspace-secret' | 'workspace-setting' | 'user-secret' | 'user-setting';
+export type RedactionMode = 'never' | 'value-only' | 'always';
+export interface KeyDef<T = unknown> {
+    /** Canonical name, e.g. `anthropic.api_key`. Lowercase, dot-separated. */
+    name: string;
+    classification: Classification;
+    /** All env-var spellings that should resolve to this key. UPPER_SNAKE_CASE. */
+    envAliases: string[];
+    default?: T;
+    /** zod validator for the parsed value. */
+    validate: ZodType<T>;
+    redact: RedactionMode;
+    /** Included in /api/config/bundle and pushSeed? */
+    exportable: boolean;
+    testConnection?: (value: T) => Promise<TestResult>;
+    rotationHint?: string;
+    /**
+     * Optional URL where users obtain this credential — e.g. a provider's
+     * API-keys page. Surfaced in the UI as a "Get an API key →" link below
+     * the field. Only set on credential-bearing keys; plain settings leave
+     * this undefined.
+     */
+    consoleUrl?: string;
+}
+/**
+ * System-level env vars provided by the OS or container runtime. Not
+ * registry-managed — they do not represent product configuration; we just
+ * read them when they happen to be set.
+ */
+export declare const SYSTEM_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Operational env vars that toggle runtime behaviour but aren't
+ * configurable settings (no UI surface, no persistence, no precedence
+ * chain). Not registry-managed.
+ */
+export declare const OPERATIONAL_ALLOWLIST: ReadonlySet<string>;
+/**
+ * The canonical registry. Order is informative (matches plan §2 grouping)
+ * but every consumer should look up by name.
+ */
+export declare const REGISTRY: ReadonlyArray<KeyDef>;
+/**
+ * Look up a registry entry by canonical name.
+ *
+ * Handles two cases:
+ *   1. Exact match on `name` — the common path.
+ *   2. Connector pattern match — concrete keys like
+ *      `connector.linear.auth` resolve to the template entry
+ *      `connector.<name>.auth`. The template's classification + redaction
+ *      flags apply to the concrete key.
+ *
+ * Returns undefined for genuinely unknown keys; callers (importer, store
+ * setters) treat this as "not in the registry, reject the write."
+ */
+export declare function getKeyDef(name: string): KeyDef | undefined;
+/**
+ * Match a concrete connector key (`connector.<name>.<slot>`) against the
+ * template entries in the registry. Returns a synthetic KeyDef carrying
+ * the template's classification/redaction/exportable flags but with the
+ * concrete `name` so audit and store rows record the actual slot, not
+ * the placeholder.
+ */
+export declare function resolveConnectorKeyDef(name: string): KeyDef | undefined;
+/**
+ * Reverse lookup: given an env-var spelling, return the registry entry that
+ * claims it as an alias. Returns `undefined` for unregistered names — the
+ * caller should fall back to the allowlists.
+ */
+export declare function getKeyDefByEnvAlias(envName: string): KeyDef | undefined;
+/**
+ * Set of every env-var spelling claimed by the registry. Used by tests and
+ * by the resolver to decide whether an env-var is "ours" vs ambient.
+ */
+export declare function allRegisteredEnvAliases(): ReadonlySet<string>;
+/**
+ * Per-provider recommended model IDs.
+ *
+ * Surfaced via the `/api/settings/schema` response on the `model.id`
+ * entry so the ProvidersPanel combobox can render a non-blocking
+ * "Recommended" group. The list is intentionally short (3–4 per
+ * provider) — power users can always type a preview-tagged value
+ * directly; the combobox never blocks freeform input.
+ *
+ * Provider keys must align 1:1 with the `model.provider` enum values
+ * — there's a registry-completeness test that guards this. Seed
+ * values below are best-effort and SHOULD BE USER-VERIFIED; the IDs
+ * shift fast and stale entries here just degrade the dropdown UX
+ * without breaking anything (free typing still works).
+ */
+export declare const RECOMMENDED_MODELS: Record<string, readonly string[]>;
+/**
+ * UI-renderable shape describing what kind of value a key accepts. Drives
+ * dropdowns, toggles, and text inputs in the settings panels — single
+ * source of truth, no hardcoded option lists in Svelte components.
+ *
+ * `enum` exposes the discrete set of allowed values (e.g. model.provider).
+ * `boolean` flags toggle inputs. Anything else (plain string, URL, regex)
+ * returns `undefined`; the UI defaults to a freeform text input.
+ */
+export type KeyConstraint = {
+    type: 'enum';
+    values: readonly string[];
+} | {
+    type: 'boolean';
+};
+/**
+ * Introspect a registered key's zod validator to recover what kind of
+ * value it accepts. Walks ZodOptional/ZodNullable/ZodDefault wrappers to
+ * the inner type. Returns `undefined` for unknown keys and for plain
+ * string-ish schemas — the UI treats absence-of-constraint as "render a
+ * text input."
+ *
+ * Implementation note: zod doesn't expose a stable type-introspection
+ * API across versions. We peek into `_def` and check `typeName` /
+ * `entries`. Wrap in try/catch and degrade to undefined if the shape
+ * changes upstream — losing a dropdown is preferable to crashing the
+ * settings panel.
+ */
+export declare function getKeyConstraint(name: string): KeyConstraint | undefined;
+/**
+ * Metadata describing a registered workspace-setting key for UI
+ * consumption. Mirrors the shape the settings panel needs: classification
+ * (so the UI knows whether to render a SecretInput vs a plain Input),
+ * env aliases (for the "shadowed by env" banner), default value, and
+ * a UI-renderable constraint.
+ *
+ * `value` is intentionally NOT included here — that's a runtime lookup
+ * against the resolver. Schema is the static shape; value comes from
+ * `GET /api/settings`.
+ */
+/**
+ * Optional per-provider recommendations on a setting entry. Currently
+ * only `model.id` carries this — the ProvidersPanel reads it off the
+ * schema to populate the combobox's "Recommended" group, keyed by the
+ * currently-selected provider. Other entries omit the field entirely.
+ */
+export interface SettingRecommendations {
+    /** Map of provider name → ordered list of recommended values. */
+    byProvider: Record<string, readonly string[]>;
+}
+export interface SettingSchemaEntry {
+    key: string;
+    classification: Classification;
+    redact: RedactionMode;
+    env_aliases: readonly string[];
+    default?: unknown;
+    constraint?: KeyConstraint;
+    /**
+     * Optional recommendations payload. Only present on `model.id` today
+     * — entries without it render as plain text inputs.
+     */
+    recommendations?: SettingRecommendations;
+}
+/**
+ * Enumerate every registered workspace-setting (non-secret) entry for
+ * the settings panels. Workspace-secrets are excluded — they go through
+ * `GET /api/secrets`, which never returns plaintext values.
+ *
+ * Connector template entries (`connector.<name>.*`) are excluded too —
+ * they're matched dynamically at resolution time, not enumerated in the
+ * UI as fixed slots.
+ */
+export declare function listWorkspaceSettingsSchema(): SettingSchemaEntry[];
+/**
+ * Flat map of canonical key → console URL for every registered key that
+ * carries one. The settings UI uses this to render a "Get an API key →"
+ * link below credential fields. The map covers BOTH workspace-secret
+ * entries (API keys, R2 credentials) and any workspace-setting that
+ * happens to grow a consoleUrl later — same lookup, single roundtrip.
+ *
+ * Keys without a registered consoleUrl are simply absent from the map.
+ */
+export declare function getAllConsoleUrls(): Record<string, string>;