@voxgig/station 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 voxgig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# station — TypeScript
+
+The TypeScript port of [station](../README.md): one control surface for
+outbound integrations.
+
+```sh
+npm test                      # conformance + integration suites
+```
+
+This port is **canonical**. `src/Station.ts` and its siblings define
+station's behaviour; every other port is a translation of them, and a
+change belongs here first.
+
+Secrets are brokered through `@voxgig/sekreto`; the config grammar
+validates through [voxgig/struct](https://github.com/voxgig/struct).
+Those are the only two runtime dependencies a station library takes
+(design §10).
+
+## Two entries, one surface
+
+`package.json` `exports` selects between them by condition:
+
+| condition | entry | |
+|---|---|---|
+| default | `dist/src/index.js` | the node entry — the whole surface |
+| `browser` | `dist/src/index.browser.js` | the same surface **minus** the file-loading half |
+
+`loadConfig`, `findConfigFile` and `configScope` are node-only: they live
+in `profile.ts`, the one module here with top-level `node:` imports, and
+the browser entry simply does not carry them. So the browser graph pulls
+no `node:` builtin at all — `test/browser.test.ts` asserts it by walking
+the *compiled* `dist` files, the same requires a bundler follows, rather
+than trusting the source. The boundary, as that test states it: the walk
+covers this package's own modules; `@voxgig/sekreto` and
+`@voxgig/struct` are recorded but not entered, since their browser
+posture is their own.
+
+That is why `profilecore.ts` exists: the pure half of profile handling
+(selection, the ref grammar, the §3.3 merge) is data-in/data-out and the
+browser entry can reach it. `profile.ts` re-exports it, so no import path
+in the node half changes.
+
+On the browser entry `Station.open()` takes `config` as an object — the
+explicit-config path, which skips file loading entirely. With no `config`
+it behaves as node does when no `station.json` exists: null config,
+repo-scoped.
+
+## Layout
+
+| | |
+|---|---|
+| `src/Station.ts` | the core: open/connect/adopt/options, sdk/create/check/warm, registry, transport middleware, the ref grammar |
+| `src/index.ts` | the node entry, and the registration that hands Station the file half |
+| `src/index.browser.ts` | the browser entry (above) |
+| `src/adapter.ts` | `featureBinding` (the one binding entry) + the carried adapter |
+| `src/shape.ts` | `normalizeConfig`/`validateConfig`: the §4 grammar, the §4.4 workarounds, the §5.2 credential scans |
+| `src/config-shape.ts` | a verbatim mirror of [`spec/config-shape.json`](../spec/config-shape.json) — generated by `make sync-shape`, never edited by hand |
+| `src/feature.ts` | the §8 three-level merge, order resolver, and descriptor-derived checker |
+| `src/factory.ts` | the process-global factory table (`provide`, §6.2) |
+| `src/loader.ts` | `loadSync`/`loadAsync`: CommonJS require + guarded dynamic import (§6.3) |
+| `src/descriptor.ts` | descriptor v1 normalizer + canonical serializer |
+| `src/secrets.ts` | the sekreto-backed broker + the placeholder |
+| `src/profile.ts` | the node-only file half: `station.json` lookup, config scope |
+| `src/profilecore.ts` | the pure half: profile selection, ref grammar, the §3.3 merge |
+| `src/events.ts` | the bounded event ring + tap |
+| `src/error.ts` | the error-code catalog |
+| `src/types.ts` | shared types; the descriptor and event shapes are pinned by the corpus, so evolve them additively |
+| `src/omnihome.ts` | locates the sibling voxgig/omni checkout (test plumbing — it is not shipped) |
+
+## Testing
+
+The conformance suite runs [`spec/station.json`](../spec/station.json) —
+the same file every port runs — through the TypeScript
+[voxgig/omni](https://github.com/voxgig/omni) runner. Set `OMNI_HOME` if
+your omni checkout is not a sibling of this repository.
+
+Note one real gap, recorded in [`spec/README.md`](../spec/README.md):
+unlike ten of the other ports, this one has **no completeness guard**. It
+hand-writes a test per section rather than deriving them from a table, so
+a section added to the corpus would silently not run *here* — in the very
+port the others are translated from. Verified by mutation: a bogus
+section added to `station.json` passes this suite and fails ten others.
+
+The integration suites run against a REAL generated SDK (generated by
+sdkgen with the station feature) and the test API servers in
+[`test/api/`](../test/api/). Without a generated checkout
+(`STATION_TEST_SDKS`, default `/home/user/voxgig-sdk`) they skip rather
+than fail.

package/dist/src/Station.d.ts

@@ -0,0 +1,238 @@
+import { Binding, PluginEntry, ResolvedInstance, SdkBlock, StationEvent, StationOptions } from './types';
+/** The FILE half of config loading, behind a seam so this module never
+ * imports it (§2.2, §17 Phase 1: no top-level `node:` imports reachable
+ * from the browser entry). The NODE entry (`index.ts`) registers
+ * `profile.ts`'s loadConfig/configScope at module load; the browser
+ * entry registers nothing, so a browser `open()` with no explicit
+ * `config` behaves exactly as node does when no station.json exists -
+ * null config, repo-scoped - rather than inventing a third state.
+ * Passing `config` (the documented browser spelling, §2.2) skips the
+ * seam entirely on both entries, which is the pre-existing
+ * explicit-config path unchanged. */
+export type ConfigFileIO = {
+    loadConfig: (from?: string) => any;
+    configScope: (from?: string) => 'repo' | 'user' | 'none';
+};
+export declare function setConfigFileIO(io: ConfigFileIO): void;
+/** §6.1: `as` IS A TAG, NOT A FREE NAME.
+ *
+ * The api comes from the SDK being passed, so the resulting ref is
+ * `<api>$<tag>` and multi-instance works imperatively too. A full ref is
+ * also accepted and is VALIDATED: its name must equal the SDK's api
+ * slug, or it is `station_instance_api`.
+ *
+ * Both forms are needed because the imperative path is where the api is
+ * implicit in an argument rather than written in a key. An `as` that
+ * took an arbitrary name would reintroduce exactly the second-identity
+ * problem the ref re-key removed: under the ref invariant
+ * `as: 'solar-eu'` would denote the untagged `solar-eu` DEFINITION, not
+ * an instance of the SDK just handed in, and registry grouping, api
+ * defaults and every ref consumer would disagree about what it is.
+ *
+ * A bare connect(SDK) with no name falls back to the descriptor slug,
+ * which is today's behaviour and why the single-instance case is
+ * unchanged to the byte. */
+export declare function instanceRef(api: string, fopts?: any): string;
+export declare function checkInstanceName(name: string): boolean;
+export declare function checkInstanceTag(tag: string): boolean;
+export declare class Station {
+    private static ambient;
+    private static ambientOpts;
+    /** §6.2's second path, and the front door the docs name.
+     *
+     * The package exported only the free `provide()` and the class had no
+     * static — so the documented `Station.provide(...)` call failed, and
+     * so did the remediation `station_no_factory` prints, which tells the
+     * user to make exactly that call. Delegates to the same
+     * process-global table the free function fills; there is one
+     * registry, not two. */
+    static provide(api: string, factory: any): void;
+    private opts;
+    private profile;
+    private broker;
+    private buffer;
+    private registry;
+    private clients;
+    private raw;
+    private repoScoped;
+    private requireProxy;
+    /** An auto-assigned tag to the DECLARED instance it stands for
+     * (§5.3). Kept beside the registry rather than inside it because the
+     * mapping exists before construction, and `blockFor` needs it during
+     * registration. */
+    private aliasOf;
+    private closed;
+    static open(opts?: StationOptions): Station;
+    static current(): Station | null;
+    static reset(): void;
+    constructor(opts?: StationOptions);
+    connect(SDK: any, opts?: any): any;
+    adopt(SDK: any, opts?: any): any;
+    private construct;
+    options(a?: any, b?: any): any;
+    _boundEntry(client: any): PluginEntry | null;
+    /** The profile block that governs an instance — its own if the
+     * profile declares it, otherwise its **api's**.
+     *
+     * `resolveProfile` builds `profile.sdk` from the declared refs alone
+     * ("an api block declares no instance, so the ref set comes from the
+     * two `sdk` maps"), shallow-merging `profile.api[a]` into each. That
+     * is right for a declared instance and leaves an IMPERATIVE one —
+     * `connect(SDK, { as: 'test' })`, named but never written into
+     * config — with no block at all. The api-level `secret`, `base` and
+     * most seriously `policy.hosts` then did not reach it, so a profile
+     * that denies egress everywhere denied nothing for a tagged client.
+     *
+     * ONE RULE, ONE PLACE: registration and the transport seam both ask
+     * here, because they disagreeing is how the credential and the
+     * allowlist came apart in the first place. */
+    private blockFor;
+    /** The DECLARED instance an assigned tag stands for, or the name
+     * itself. `create('stripe$prod')` registers under `stripe$1`, and
+     * every question about that client's configuration — its secret, its
+     * base, its egress policy — is a question about `stripe$prod`. */
+    private declaredRef;
+    _register(client: any, config: any, options: any, _calleropts: any, fopts?: any): {
+        binding: Binding;
+        profilePlugin?: SdkBlock;
+    };
+    private descriptorCache;
+    /** The descriptor describes the API, and is SHARED by every instance
+     * of it — which is §7.4's own reasoning for why the effective secret
+     * name moved to `Binding` and is not read off the descriptor.
+     *
+     * The same argument applies to feature activation, and this did not
+     * follow it: the cache is keyed by slug alone while
+     * `normalizeDescriptor`'s second argument decides each feature row's
+     * `active`. So two instances of one api constructed with different
+     * feature maps shared the FIRST one's feature state, and
+     * `descriptorOf()` / `canonicalDescriptor()` became
+     * construction-order-dependent.
+     *
+     * Normalized with no per-instance features, so the shared value holds
+     * only API-stable metadata — which is what `factory.ts` already does
+     * when it normalizes at provide time. Per-instance activation is
+     * `featuresOf(name)`'s answer, and always was. */
+    private describe;
+    _hoist(name: string, value: string): void;
+    _transport(name: string, inner: any, fctx: any, fullurl: string, fetchdef: any): Promise<any>;
+    private emitHttp;
+    private emitErr;
+    _opEvent(name: string, ctx: any, outcome: string): void;
+    plugins(): {
+        name: string;
+        api: string;
+        slug: string;
+        descriptor: any;
+        rung: string;
+        secretname?: string;
+        warnings: string[];
+    }[];
+    /** The instance, constructed on first call and CACHED: same name ->
+     * same object. That caching is what makes "get it where you need it"
+     * a real instruction - call it in a request handler, in a worker, in
+     * a test, and the first call pays construction while the rest are a
+     * map lookup.
+     *
+     * SYNCHRONOUS (§6.3), which is what bounds the loader to CommonJS. */
+    sdk(name: string): any;
+    /** An UNCACHED client from the same resolved config plus overrides,
+     * for the case that genuinely wants a distinct one - a per-request
+     * credential scope, a test double. Deliberately the longer name.
+     *
+     * It registers under an AUTO-ASSIGNED TAG, because §7.5 registers
+     * every constructed adapter under its instance name and
+     * `station_bound_twice` fires on a second binding of one name: a
+     * second `create('stripe')` would otherwise throw, which is exactly
+     * the per-request case this exists for. The tag is the lowest unused
+     * positive integer, so an auto-tagged instance is an ORDINARY
+     * instance rather than a parallel identity scheme - `plugins()`, the
+     * placeholder, the event stream and `station_bound_twice` all keep
+     * working on one identity model.
+     *
+     * The SECRET NAME does not follow the assigned tag: it resolves from
+     * the DECLARED instance the tag was assigned under, so every client
+     * of one instance shares one broker cache entry rather than
+     * re-resolving per request (§5.3). */
+    create(name: string, overrides?: any): any;
+    /** The lowest positive integer tag not already taken, by a LIVE
+     * instance or a DECLARED one.
+     *
+     * The registry alone was not enough: a profile may declare
+     * `stripe$1`, and until something constructs it `registry.has` says
+     * false — so `create('stripe$prod')` took that identity for a client
+     * built from the `stripe$prod` block. `instances()` then reported the
+     * declared `stripe$1` as live with the wrong client, and a later
+     * `sdk('stripe$1')` failed `station_bound_twice` against a binding
+     * that was never its own. Declaration reserves the name whether or
+     * not it has been built. */
+    private autotag;
+    private build;
+    /** §6.2's three paths, in order of preference: self-registration,
+     * `Station.provide`, then the loader. */
+    private resolveFactory;
+    /** `package` is honoured only from repo-scoped config (§6.3), and a
+     * user-level one is IGNORED WITH A WARNING rather than imported - it
+     * names code to load and sits outside the repo's review boundary. */
+    private loaderPackage;
+    /** ts/js only: preload ESM packages into the factory table, after
+     * which `sdk()` is synchronous again for everything (§6.3). One
+     * `await` at startup rather than one per call site. */
+    load(): Promise<void>;
+    /** The merged, ordered feature set for one instance, WITH
+     * PROVENANCE (§8.7): which config level set each value.
+     *
+     * Provenance is the half that makes a fleet view usable rather than
+     * merely correct - at 26 instances "why is retry off here" is the
+     * question, and a merged map alone cannot answer it. */
+    featuresOf(name: string): {
+        ordered: string[];
+        merged: {
+            [k: string]: any;
+        };
+        from: {
+            [k: string]: {
+                [k: string]: string;
+            };
+        };
+    };
+    /** The fleet feature view: instance x feature, effective options, and
+     * which config level set each (§8.7). */
+    features(filter?: string | {
+        instance?: string;
+        api?: string;
+        feature?: string;
+    }): any[];
+    /** Eagerly resolve and construct every ACTIVE instance - for CI
+     * (§6.6). The point is to turn availability errors, which are
+     * deliberately deferred to first use, into one failure at a moment
+     * somebody is watching. */
+    check(): {
+        ok: string[];
+        failed: {
+            name: string;
+            code?: string;
+            message: string;
+        }[];
+    };
+    /** Batch-resolve secrets for ACTIVE instances (§5.5).
+     *
+     * With no argument it warms the active ones only, because reaching
+     * for a credential belonging to a disabled integration is the wrong
+     * default. `warm(names)` warms exactly what it is given, inactive
+     * included, because an explicit name is an explicit request. */
+    warm(names?: string[]): Promise<{
+        warmed: string[];
+        missed: string[];
+    }>;
+    instances(): ResolvedInstance[];
+    descriptorOf(slug: string): any;
+    canonicalDescriptor(slug: string): string;
+    events(): StationEvent[];
+    tap(fn: (ev: StationEvent) => void): () => void;
+    status(): any;
+    redact(text: string): string;
+    refreshSecrets(): void;
+    close(): void;
+    private emit;
+}