@crouter/api 0.3.387 → 0.3.388

package/dist/core/command-plugins/endpoint.js

@@ -0,0 +1,51 @@
+import { validateEnvVarName } from '../env-name.js';
+/** Hosts `http:` is allowed for: loopback, Docker's host alias, and any
+ *  `*.localhost` name (RFC 6761 reserves it for local use; the local
+ *  directory and provider stacks serve `http://<svc>.localhost:<port>`). */
+function isLoopbackHostname(hostname) {
+    return hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1' || hostname === 'host.docker.internal';
+}
+export function validateEndpoint(endpoint) {
+    const errors = [];
+    if (typeof endpoint !== 'string')
+        errors.push('endpoint must be a string');
+    else {
+        try {
+            const url = new URL(endpoint);
+            if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHostname(url.hostname)))
+                errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)');
+            else if (url.username || url.password || url.hash)
+                errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)');
+        }
+        catch {
+            errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)');
+        }
+    }
+    return { isValid: errors.length === 0, errors };
+}
+export function normalizeEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        const pathname = url.pathname.length > 1 && url.pathname.endsWith('/') ? url.pathname.slice(0, -1) : url.pathname;
+        return `${url.protocol}//${url.host}${pathname}${url.search}`;
+    }
+    catch {
+        return endpoint;
+    }
+}
+export function validateHttpPluginTransport(raw) {
+    const errors = [];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return { errors: ['transport must be an object'] };
+    const transport = raw;
+    const unknown = Object.keys(transport).filter((key) => !['kind', 'endpoint', 'authEnv'].includes(key));
+    if (unknown.length)
+        errors.push(`transport has unknown keys: ${unknown.join(', ')}`);
+    if (transport.kind !== 'http')
+        errors.push('transport.kind must be "http"');
+    const endpoint = validateEndpoint(transport.endpoint);
+    errors.push(...endpoint.errors);
+    if (transport.authEnv !== undefined)
+        errors.push(...validateEnvVarName(transport.authEnv).errors);
+    return errors.length ? { errors } : { transport: { kind: 'http', endpoint: normalizeEndpoint(transport.endpoint), ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}) }, errors };
+}

package/dist/core/config.d.ts

@@ -0,0 +1,233 @@
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig, ProviderOptionsConfig } from '../types.js';
+import { type BindingId } from './keybindings/catalog.js';
+import type { RotationConfig } from './subscription-state.js';
+export declare function configPath(scope: Scope): string | null;
+export declare function statePath(scope: Scope): string | null;
+export interface BrokerConfigSnapshot {
+    user: ResolvedScopeConfig;
+    launch: MergedLaunchConfig;
+    rotation: RotationConfig;
+}
+export declare function installBrokerConfigSnapshot(snapshot: BrokerConfigSnapshot): void;
+export declare function brokerConfigSnapshot(): BrokerConfigSnapshot | undefined;
+export declare function readConfig(scope: Scope): ResolvedScopeConfig;
+export declare function readConfigAtRoot(root: string): ResolvedScopeConfig;
+export declare function readState(scope: Scope): ScopeState;
+export type RawSettingsTarget = {
+    scope: 'user';
+} | {
+    scope: 'profile';
+    profileId: string;
+};
+export declare class InvalidRawSettingsError extends Error {
+    constructor(cause: unknown);
+}
+export declare function readRawSettingsForTarget(target: RawSettingsTarget): {
+    settings: Record<string, unknown> | null;
+    revision: string;
+};
+export declare function replaceRawSettingsForTarget(target: RawSettingsTarget, next: Record<string, unknown>, ifRevision: string): {
+    revision: string;
+    changed: boolean;
+};
+type RawConfig = Record<string, unknown>;
+export declare function updateRawConfigAtomically(scope: Scope, mutate: (latest: RawConfig) => RawConfig): RawConfig;
+export declare function writeConfig(scope: Scope, config: ScopeConfig): void;
+export declare function writeRawConfig(scope: Scope, config: Partial<ScopeConfig>): void;
+export declare function writeState(scope: Scope, state: ScopeState): void;
+export declare function ensureScopeInitialized(scope: Scope, root: string): void;
+/** Normalize the user-owned list of attach actions allowed to bridge through an
+ * occupied tmux root binding. Unknown and non-attach ids have no effect. */
+export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
+type LegacyModelRouteConfig = Omit<ModelRouteConfig, 'models'> & {
+    models: Partial<Record<ModelStrength, string>>;
+};
+/** Read configuration exposes legacy sparse routes separately during the
+ * one-release cutover; launch code only treats `modelRoutes` as complete. */
+export type ResolvedScopeConfig = ScopeConfig & {
+    legacyModelRoutes?: Record<string, LegacyModelRouteConfig>;
+};
+/** One malformed `bin` declaration. The read path retains these as doctor
+ *  findings rather than letting malformed config break a node launch. */
+export interface BinDeclarationIssue {
+    name: string;
+    message: string;
+}
+/** Validate raw `bin` declaration shape without touching the filesystem.
+ *  Install uses these findings as a hard gate for plugin manifests; scope
+ *  resolution reports them through `crtr sys doctor` and continues. */
+export declare function binDeclarationIssues(raw: unknown): BinDeclarationIssue[];
+/** Normalize one raw `bin` block (a scope `config.json`'s or a plugin
+ *  manifest's) to name → root-relative path. Invalid entries never become
+ *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
+export declare function normalizeBin(raw: unknown): Record<string, string>;
+export interface HumanActionDeclarationIssue {
+    name: string;
+    reason: string;
+    block?: true;
+}
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export declare function humanActionDeclarationIssues(raw: unknown): HumanActionDeclarationIssue[];
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export declare function normalizeHumanActions(raw: unknown): Record<string, HumanActionConfig>;
+/** STRICT install-time validation for a plugin-declared `bin` block. Target
+ *  filesystem state is checked later by Doctor because it can change after
+ *  install. */
+export declare function invalidPluginBinReasons(raw: unknown): string[];
+/** Normalize a plugin manifest's advisory executable requirements. Invalid
+ *  declarations stay out of the read path; source installs reject them through
+ *  `invalidPluginRequiresReasons`. */
+export declare function normalizeRequires(raw: unknown): Record<string, string>;
+/** STRICT install-time validation for a plugin's advisory `requires` block.
+ *  A missing executable is advisory; only malformed declarations fail install. */
+export declare function invalidPluginRequiresReasons(raw: unknown): string[];
+/** The ACTIVE page-component catalog every authoring, validation, daemon,
+ *  inbox, and TUI consumer resolves: the user scope's own `page_components`
+ *  entries plus the contributions of every ENABLED plugin installed under that
+ *  same root, plugin name-sorted for determinism (directory listing order is
+ *  filesystem-dependent). Installing, updating, or removing a plugin therefore
+ *  adds, changes, or retires its components with no config edit.
+ *
+ *  User scope only, deliberately: this catalog is read from the daemon, the
+ *  CLI, and the inbox TUI, whose ambient cwds differ, and a page slot whose
+ *  validity depended on which directory a process happened to start in would
+ *  validate in one surface and fail in another. `page_components` has always
+ *  been a user-scope block (`readConfig('user')`); its plugin channel keeps
+ *  that boundary.
+ *
+ *  Throws on a duplicate kind or derived JSX tag across sources, and on a
+ *  plugin whose block is malformed — matching the existing catalog validation
+ *  style, where a bad `page_components` block already fails config read rather
+ *  than silently dropping a component the product expects to be authorable.
+ *  Install-time validation (`invalidPageComponentsReasons`) is what keeps a
+ *  malformed block from ever reaching this path. */
+export declare function resolvePageComponents(): PageComponentRegistration[];
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export declare function invalidPluginKindsReasons(raw: unknown): string[];
+/** Raw (un-defaulted) partial config for one scope, or null if the scope has
+ *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
+ *  scopes onto each other WITHOUT each scope's own default-fill masking a
+ *  lower-precedence scope's real customization (see that function's comment
+ *  for why `readConfig(scope)`, which already defaults-fills, is unusable
+ *  for cross-scope layering). */
+export declare function readRawConfigAtRoot(root: string): Partial<ScopeConfig> | null;
+export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> | null;
+export interface MergedLaunchConfig {
+    kinds: Record<string, KindConfig>;
+    modelLadders: ModelLaddersConfig;
+    /** Per-provider behavior options keyed by runtime provider id, merged
+     *  per provider across scopes (project stack > profile > user). */
+    providerOptions: Record<string, ProviderOptionsConfig>;
+    /** Complete declared routes. Every route here has all four strengths. */
+    modelRoutes?: Record<string, ModelRouteConfig>;
+    /** Read-only compatibility view for sparse routes written before complete
+     * routes were required. New route persistence never produces this shape. */
+    legacyModelRoutes?: Record<string, LegacyModelRouteConfig>;
+    modelRouting?: ModelRoutingConfig;
+    /** The merged `spawnEnv.allow` set (project stack > profile > user >
+     *  builtin, additive) — read by `buildOperationalEnvBase`
+     *  (`core/runtime/spawn-env.ts`) as source C of the broker spawn-env
+     *  boundary. */
+    spawnEnv: {
+        allow: string[];
+    };
+}
+/** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
+ *  project stack > profile > user > builtin precedence — the same precedence
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. A kind or ladder cell declared at a
+ *  more-specific scope shadows the same key from a less-specific scope; the
+ *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
+ *  widened by a selected profile's `projects`) layers nearest-root-strongest;
+ *  a key no scope declares falls through to the builtin default registry
+ *  (`defaultScopeConfig().kinds` / `.modelLadders`).
+ *
+ *  Layers RAW (un-defaulted) partial config per scope, not `readConfig(scope)`
+ *  — `readConfig` already fills in every default kind for a scope that
+ *  customizes even one, so naively overlaying two already-defaulted
+ *  `ScopeConfig.kinds` objects would let an untouched project-scope kind
+ *  (silently defaulted) clobber a real user-scope customization of that same
+ *  kind. Layering the raw partials avoids that.
+ *
+ *  Callers (launch, kind registry) go through this function rather than
+ *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
+ *  extensions/`availableTo` all honor the same profile + multi-project
+ *  precedence.
+ *
+ *  `targetCwd`/`targetProfileId` default to this PROCESS's own ambient cwd
+ *  and `CRTR_PROFILE_ID` — correct for a caller resolving config for itself
+ *  (front-door commands, kind listing). A caller resolving config on behalf
+ *  of a DIFFERENT node (the broker spawn-env boundary or cron executor — both
+ *  run inside the daemon, whose ambient cwd/profile is the daemon's own, not
+ *  the target node's) MUST pass the target's own cwd/profile explicitly, or
+ *  `spawnEnv.allow` resolves from the wrong scope entirely (the C-1
+ *  follow-up fix this parameterization exists for). */
+export declare function readMergedLaunchConfig(targetCwd?: string, targetProfileId?: string | null): MergedLaunchConfig;
+/** The effective `KindConfig` for one full kind string (top-level, e.g.
+ *  `developer`, or sub-kind, e.g. `audit/security`), across
+ *  project > user > builtin precedence. Returns `undefined` for a kind no
+ *  scope registers — existence is deliberately NOT validated here (kind
+ *  existence/launch-menu enumeration is a caller concern); this only
+ *  resolves the config for a kind the caller already knows about. */
+export declare function resolveKindConfig(kind: string): KindConfig | undefined;
+/** The sub-kinds available to spawn FROM a given top-level kind — every
+ *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
+ *  its own top-level ancestor, e.g. `audit/security` defaults to
+ *  `['audit']`) includes `kind` or `'*'`. The single source both `sys
+ *  prompt-review --list`'s `subPersonas` metadata and the live sub-persona
+ *  spawn-menu splice (`core/substrate/delivery/render-boot.ts`) read, so the two can never
+ *  drift apart. Sorted by full kind name for stable rendering. */
+export declare function subKindsAvailableTo(kind: string): {
+    kind: string;
+    whenToUse: string;
+}[];
+/** Persist an EXPLICIT sparse `modelLadders` intent at one config root: the
+ *  patch's rungs (and `defaultProvider`) are merged over whatever sparse ladder
+ *  is already on disk, and every untouched rung stays absent so it keeps
+ *  re-deriving from the running build's registry.
+ *
+ *  Ladder edits must come through here rather than `updateConfig`, because that
+ *  path infers what to persist by diffing the mutated config against the merged
+ *  baseline: setting a rung to the value that happens to be today's compiled
+ *  default produces an empty diff and silently persists nothing, so the choice
+ *  evaporates as soon as the default moves. Explicit intent is recorded as
+ *  written. Mirrors `persistDefaultKindModel`. */
+export declare function persistModelLadders(root: string, patch: {
+    defaultProvider?: ModelProvider;
+    anthropic?: Partial<Record<ModelStrength, string>>;
+    openai?: Partial<Record<ModelStrength, string>>;
+}): void;
+/** Persist one complete route at one exact config root. The route is the only
+ * raw route entry touched; unrelated routes and local ladder defaults remain
+ * absent. Pass `undefined` to remove this scope's entry, which resumes lower
+ * scope inheritance rather than introducing a tombstone. */
+export declare function persistModelRoute(root: string, routeId: string, route: ModelRouteConfig | undefined): void;
+/** Mutate one exact config root. Setup uses this for profile and explicit
+ * project targets that cannot be represented by the user/project Scope enum. */
+export declare function updateConfigAtRoot(root: string, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+export declare function updateConfig(scope: Scope, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+/** Persist one sparse kind-model field at an exact config root. The sparse
+ * patch keeps every unrelated kind and launch knob inherited from lower
+ * scopes instead of freezing a materialized registry snapshot. */
+export declare function persistDefaultKindModel(opts: {
+    root: string;
+    kind: string;
+    model: string;
+    orchestrator?: boolean;
+}): {
+    path: string;
+    field: 'model' | 'orchestratorModel';
+};
+export declare function updateState(scope: Scope, mutate: (s: ScopeState) => void): ScopeState;
+export {};