@hypersoniclabs/helix-cli 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @hypersoniclabs/helix-cli
+
+`helix` — the **HELIX creator CLI**: scaffold, validate, and publish Instant Worlds to the HELIX
+backend. It shares bundle validation with the server via `@hypersoniclabs/helix-manifest`, so "validate passed but
+publish failed" can't happen for contract reasons.
+
+## Install
+
+```bash
+npm install -g @hypersoniclabs/helix-cli
+```
+
+## Authentication
+
+The CLI authenticates with a **client token** (a long-lived API token tied to your account).
+
+1. Generate one in the **Creator Hub** → *Settings → Client Tokens*.
+2. Run `helix login` and paste it (or `helix login --token <token>`).
+
+The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
+`Authorization: Bearer <token>` on publish calls. `helix login` validates it against
+`GET /api/v1/users/me` before saving and reads the token's `exp` so the CLI knows when it lapses.
+
+> Point the CLI at a backend with `--api-url` or the `HELIX_API_URL` env var
+> (default `http://localhost:5000`).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `helix login [--api-url <url>] [--token <t>]` | Store a client token for the CLI. |
+| `helix logout` | Remove the stored token. |
+| `helix whoami` | Show current login status. |
+| `helix init <dir>` | Scaffold a minimal Three.js world (`helix.json` + `index.html` + `main.js`). |
+| `helix validate [dir]` | Validate a bundle locally — the exact rules the server enforces. |
+| `helix publish [dir]` | Validate → resolve/create the world → upload files → finalize → print the play URL. |
+| `helix list` | List your worlds. |
+
+## Publish flow
+
+`helix publish` maps directly onto the backend's Instant World API:
+
+1. `checkBundle` validates `helix.json` + files via `@hypersoniclabs/helix-manifest`.
+2. `GET /api/v1/instant-worlds/me` → reuse the world with the manifest's slug, else
+   `POST /api/v1/instant-worlds`.
+3. `POST /api/v1/instant-worlds/:id/builds` → presigned upload tickets.
+4. Files PUT directly to storage (6 concurrent), content-type/length bound to each ticket.
+5. `POST /api/v1/instant-worlds/:id/builds/:buildId/finalize` → byte-exact verify, activate, publish.
+6. `GET /api/v1/instant-worlds/:slug` → the play URL.
+
+The programmatic surface (`publishWorld`, `checkBundle`, `whoAmI`, …) is exported from the package
+main, so an MCP server can drive the exact same code paths an agent would.
+
+## Develop
+
+```bash
+npm install
+npm test       # jest
+npm run build  # tsc → dist/ (bin: dist/index.js)
+npm run lint
+```

package/dist/ability.d.ts

@@ -0,0 +1,73 @@
+export type ManifestIssue = {
+    path: string;
+    message: string;
+};
+export type ParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string[];
+};
+export type AbilityValidator = {
+    validateAbilityManifest(value: unknown): ManifestIssue[];
+    /** Present on the real vendored artifact — enables the install-time system-pin check (gate 2). */
+    satisfiesSystemPin?(systemVersion: string, range: string): boolean;
+    /** Frozen semver primitives — the single source of `^`/`~` + prerelease ordering (reused by resolvePins). */
+    parseSemver?(version: string): ParsedSemver | null;
+    compareSemver?(a: ParsedSemver, b: ParsedSemver): number;
+    SYSTEM_IDENTITY?: {
+        id: string;
+        version: string;
+        skeleton: string;
+    };
+};
+export type InstalledIndexValidator = {
+    validateInstalledIndex(value: unknown): ManifestIssue[];
+    isResolvedEntry(entry: Record<string, unknown>): boolean;
+};
+export type AbilityManifestLike = {
+    id: string;
+    version: string;
+    title: string;
+    system: {
+        id: string;
+        version: string;
+        skeleton: string;
+    };
+    activation: {
+        mode: string;
+    };
+    entry: string;
+    configSchema: string;
+    clips?: {
+        name: string;
+        src: string;
+    }[];
+};
+export declare function loadVendoredValidator(): Promise<AbilityValidator>;
+export declare function loadInstalledIndexValidator(): Promise<InstalledIndexValidator>;
+export type AbilityBundleCheck = {
+    manifest: AbilityManifestLike | null;
+    errors: string[];
+};
+/** True when an ability's built entry has three.js bundled in rather than left external. */
+export declare function bundlesThree(entrySource: string): boolean;
+/** Validates an ability bundle directory: ability.json against the frozen contract + referenced files exist. */
+export declare function checkAbilityBundle(root: string, validator: AbilityValidator): AbilityBundleCheck;
+export declare const MODULES_DIR = "helix_modules";
+export declare const INSTALLED_INDEX = "installed.json";
+export type InstallResult = {
+    id: string;
+    version: string;
+    /** Bundle path relative to the index (== the ability id). */
+    path: string;
+    /** Total entries in installed.json after this install. */
+    installedCount: number;
+};
+/**
+ * `helix install <bundle> --first-party` (a.k.a. `--local`): the FIRST-PARTY whole-bundle copy —
+ * validates, copies the bundle (code AND clips) into `<worldDir>/helix_modules/<id>/`, and upserts a
+ * v1 local `installed.json` entry. Used by the engine devs to test co-located assets; consumer
+ * worlds use `helix install` (no path) which is code-only with assets streaming from the CDN.
+ */
+export declare function installLocalAbility(bundleDir: string, worldDir: string, validator: AbilityValidator, indexValidator: InstalledIndexValidator): InstallResult;

package/dist/ability.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALLED_INDEX = exports.MODULES_DIR = void 0;
+exports.loadVendoredValidator = loadVendoredValidator;
+exports.loadInstalledIndexValidator = loadInstalledIndexValidator;
+exports.bundlesThree = bundlesThree;
+exports.checkAbilityBundle = checkAbilityBundle;
+exports.installLocalAbility = installLocalAbility;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+// The vendor file is ESM; this package compiles to CommonJS, where tsc downlevels `import()` to
+// `require()` — which cannot load ESM. The Function indirection keeps the native dynamic import.
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+async function loadVendoredValidator() {
+    const url = (0, node_url_1.pathToFileURL)((0, node_path_1.join)(__dirname, '..', 'vendor', 'ability-manifest.mjs')).href;
+    return (await dynamicImport(url));
+}
+async function loadInstalledIndexValidator() {
+    const url = (0, node_url_1.pathToFileURL)((0, node_path_1.join)(__dirname, '..', 'vendor', 'installed-index.mjs')).href;
+    return (await dynamicImport(url));
+}
+// three's bundled source carries its REVISION constant (`const REVISION = '172'`) and core class
+// declarations; an external bare import (`import ... from 'three'`) produces only property access
+// against the namespace (`THREE.Vector3`), never these definition forms. Either signal therefore
+// means three got inlined — which forks the instance and silently breaks instanceof across the host.
+const THREE_REVISION = /\bREVISION\s*=\s*['"]\d+['"]/;
+const THREE_CORE_CLASS = /\bclass\s+(Object3D|BufferGeometry|Matrix4|Vector3|Quaternion|Euler|PerspectiveCamera|WebGLRenderer|Material)\b/g;
+/** True when an ability's built entry has three.js bundled in rather than left external. */
+function bundlesThree(entrySource) {
+    if (THREE_REVISION.test(entrySource))
+        return true;
+    const classes = new Set(entrySource.match(THREE_CORE_CLASS) ?? []);
+    return classes.size >= 2;
+}
+/** Validates an ability bundle directory: ability.json against the frozen contract + referenced files exist. */
+function checkAbilityBundle(root, validator) {
+    const manifestPath = (0, node_path_1.join)(root, 'ability.json');
+    if (!(0, node_fs_1.existsSync)(manifestPath)) {
+        const hint = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, 'helix.json'))
+            ? 'this looks like a WORLD bundle (helix.json) — use `helix validate`'
+            : 'is this the built bundle directory (dist/)?';
+        return { manifest: null, errors: [`no ability.json at the bundle root — ${hint}`] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        return { manifest: null, errors: [`ability.json is not valid JSON: ${err instanceof Error ? err.message : err}`] };
+    }
+    const issues = validator.validateAbilityManifest(parsed);
+    if (issues.length) {
+        return { manifest: null, errors: issues.map((i) => `ability.json ${i.path === '' ? '(root)' : i.path}: ${i.message}`) };
+    }
+    const manifest = parsed;
+    const errors = [];
+    // System-pin check against the vendored validator's own system identity (gate 2: refused at
+    // install, not just at load) — the artifact banner records which system version it came from.
+    const system = validator.SYSTEM_IDENTITY;
+    if (system !== undefined && validator.satisfiesSystemPin !== undefined) {
+        if (manifest.system.id !== system.id) {
+            errors.push(`system.id '${manifest.system.id}' does not match the running system '${system.id}'`);
+        }
+        else if (!validator.satisfiesSystemPin(system.version, manifest.system.version)) {
+            errors.push(`system.version '${manifest.system.version}' is not satisfied by the system version ${system.version}`);
+        }
+        else if (manifest.system.skeleton !== system.skeleton) {
+            errors.push(`system.skeleton '${manifest.system.skeleton}' does not match the running skeleton standard '${system.skeleton}'`);
+        }
+    }
+    const referenced = [manifest.entry, manifest.configSchema, ...(manifest.clips ?? []).map((c) => c.src)];
+    for (const rel of referenced) {
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, rel)))
+            errors.push(`referenced file missing from the bundle: ${rel}`);
+    }
+    // Single-instance invariant: the world supplies the one shared three; the entry must import it,
+    // not ship its own copy. Build the ability with `--external three`.
+    const entryPath = (0, node_path_1.join)(root, manifest.entry);
+    if ((0, node_fs_1.existsSync)(entryPath) && bundlesThree((0, node_fs_1.readFileSync)(entryPath, 'utf8'))) {
+        errors.push(`${manifest.entry} inlines three.js — rebuild the ability with \`--external three\` so the world supplies the single shared instance`);
+    }
+    return { manifest: errors.length ? null : manifest, errors };
+}
+exports.MODULES_DIR = 'helix_modules';
+exports.INSTALLED_INDEX = 'installed.json';
+/**
+ * `helix install <bundle> --first-party` (a.k.a. `--local`): the FIRST-PARTY whole-bundle copy —
+ * validates, copies the bundle (code AND clips) into `<worldDir>/helix_modules/<id>/`, and upserts a
+ * v1 local `installed.json` entry. Used by the engine devs to test co-located assets; consumer
+ * worlds use `helix install` (no path) which is code-only with assets streaming from the CDN.
+ */
+function installLocalAbility(bundleDir, worldDir, validator, indexValidator) {
+    const check = checkAbilityBundle(bundleDir, validator);
+    if (check.errors.length || check.manifest === null) {
+        throw new Error(`bundle refused:\n${check.errors.map((e) => `  - ${e}`).join('\n')}`);
+    }
+    const { id, version } = check.manifest;
+    const modulesDir = (0, node_path_1.join)(worldDir, exports.MODULES_DIR);
+    const indexPath = (0, node_path_1.join)(modulesDir, exports.INSTALLED_INDEX);
+    let index = [];
+    if ((0, node_fs_1.existsSync)(indexPath)) {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(indexPath, 'utf8'));
+        const issues = indexValidator.validateInstalledIndex(parsed);
+        if (issues.length) {
+            throw new Error(`existing ${exports.INSTALLED_INDEX} is invalid (delete it to regenerate):\n${issues.map((i) => `  ${i.path}: ${i.message}`).join('\n')}`);
+        }
+        index = parsed;
+    }
+    const target = (0, node_path_1.join)(modulesDir, id);
+    (0, node_fs_1.rmSync)(target, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)(target, { recursive: true });
+    (0, node_fs_1.cpSync)(bundleDir, target, { recursive: true });
+    index = index.filter((entry) => entry.id !== id);
+    index.push({ id, version, path: id });
+    index.sort((a, b) => a.id.localeCompare(b.id));
+    (0, node_fs_1.writeFileSync)(indexPath, `${JSON.stringify(index, null, 2)}\n`);
+    return { id, version, path: id, installedCount: index.length };
+}
+//# sourceMappingURL=ability.js.map

package/dist/ability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ability.js","sourceRoot":"","sources":["../src/ability.ts"],"names":[],"mappings":"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"}

package/dist/api.d.ts

@@ -0,0 +1,24 @@
+import { CliCredentials } from './config';
+type NestErrorBody = {
+    statusCode?: number;
+    message?: string | string[];
+    error?: string;
+};
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: NestErrorBody;
+    constructor(status: number, body: NestErrorBody);
+    private static messages;
+    render(): string;
+}
+export declare class HelixApi {
+    private readonly baseUrl;
+    private token;
+    constructor(baseUrl: string, token?: string | null);
+    setToken(token: string): void;
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    requestItem<T>(method: string, path: string, body?: unknown): Promise<T>;
+    static forCredentials(creds: CliCredentials): HelixApi;
+}
+export declare function uploadToTicket(url: string, body: Buffer, contentType: string, cacheControl?: string): Promise<void>;
+export {};

package/dist/api.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HelixApi = exports.ApiError = void 0;
+exports.uploadToTicket = uploadToTicket;
+class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(ApiError.messages(body).join('; ') || `HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+    }
+    static messages(body) {
+        if (Array.isArray(body.message))
+            return body.message;
+        if (typeof body.message === 'string')
+            return [body.message];
+        return [];
+    }
+    // Rendered for terminal humans.
+    render() {
+        const heading = this.body.error ?? 'Error';
+        const lines = [`✖ ${heading} (${this.status})`];
+        for (const msg of ApiError.messages(this.body))
+            lines.push(`  - ${msg}`);
+        return lines.join('\n');
+    }
+}
+exports.ApiError = ApiError;
+class HelixApi {
+    baseUrl;
+    token;
+    constructor(baseUrl, token = null) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                'content-type': 'application/json',
+                ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const problem = (await res.json().catch(() => ({})));
+            throw new ApiError(res.status, problem);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    // Convenience for endpoints that return a SingleResponseDto ({ item: T }).
+    async requestItem(method, path, body) {
+        const envelope = await this.request(method, path, body);
+        return envelope.item;
+    }
+    static forCredentials(creds) {
+        return new HelixApi(creds.apiUrl, creds.token);
+    }
+}
+exports.HelixApi = HelixApi;
+// Uploads a file body to a presigned URL. Content-Type (and, for package
+// uploads, Cache-Control) are part of the signature, so the client must echo
+// them exactly or R2 rejects the PUT with a signature mismatch.
+async function uploadToTicket(url, body, contentType, cacheControl) {
+    const res = await fetch(url, {
+        method: 'PUT',
+        body: new Uint8Array(body),
+        headers: {
+            'content-type': contentType,
+            ...(cacheControl ? { 'cache-control': cacheControl } : {}),
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`upload failed (${res.status}): ${await res.text().catch(() => '')}`);
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/bundle.d.ts

@@ -0,0 +1,12 @@
+import { NormalizedHelixManifest } from '@hypersoniclabs/helix-manifest';
+export type BundleFile = {
+    path: string;
+    size: number;
+    absolutePath: string;
+};
+export type BundleCheck = {
+    manifest: NormalizedHelixManifest | null;
+    files: BundleFile[];
+    errors: string[];
+};
+export declare function checkBundle(root: string): BundleCheck;

package/dist/bundle.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkBundle = checkBundle;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.vscode', '.idea']);
+function walk(dir, root, out) {
+    for (const name of (0, node_fs_1.readdirSync)(dir)) {
+        if (IGNORED_DIRS.has(name))
+            continue;
+        const absolutePath = (0, node_path_1.join)(dir, name);
+        const stat = (0, node_fs_1.statSync)(absolutePath);
+        if (stat.isDirectory()) {
+            walk(absolutePath, root, out);
+        }
+        else {
+            out.push({ path: (0, node_path_1.relative)(root, absolutePath).replaceAll('\\', '/'), size: stat.size, absolutePath });
+        }
+    }
+}
+// Local validation with the exact same rules the server enforces at publish —
+// shared via @hypersoniclabs/helix-manifest, so "validate passed but publish failed" can't
+// happen for contract reasons.
+function checkBundle(root) {
+    const errors = [];
+    const files = [];
+    try {
+        walk(root, root, files);
+    }
+    catch (err) {
+        return { manifest: null, files: [], errors: [`cannot read directory: ${err instanceof Error ? err.message : err}`] };
+    }
+    const manifestFile = files.find((f) => f.path === helix_manifest_1.MANIFEST_FILENAME);
+    let manifest = null;
+    if (!manifestFile) {
+        errors.push(`no ${helix_manifest_1.MANIFEST_FILENAME} found at the bundle root`);
+    }
+    else {
+        const result = (0, helix_manifest_1.parseManifest)((0, node_fs_1.readFileSync)(manifestFile.absolutePath, 'utf8'));
+        if (result.valid)
+            manifest = result.manifest;
+        else
+            errors.push(...result.errors);
+    }
+    if (files.length > helix_manifest_1.BUNDLE_MAX_FILES)
+        errors.push(`${files.length} files — limit is ${helix_manifest_1.BUNDLE_MAX_FILES}`);
+    let total = 0;
+    for (const file of files) {
+        total += file.size;
+        if (!helix_manifest_1.BUNDLE_PATH_PATTERN.test(file.path))
+            errors.push(`invalid path: ${file.path}`);
+        else if ((0, helix_manifest_1.bundleContentType)(file.path) === null)
+            errors.push(`file type not allowed: ${file.path}`);
+        if (file.size > helix_manifest_1.BUNDLE_MAX_FILE_BYTES)
+            errors.push(`${file.path} is ${file.size} bytes — per-file limit is ${helix_manifest_1.BUNDLE_MAX_FILE_BYTES}`);
+        if (file.size === 0)
+            errors.push(`${file.path} is empty`);
+    }
+    if (total > helix_manifest_1.BUNDLE_MAX_TOTAL_BYTES)
+        errors.push(`bundle is ${total} bytes — limit is ${helix_manifest_1.BUNDLE_MAX_TOTAL_BYTES}`);
+    if (manifest && !files.some((f) => f.path === manifest.entry)) {
+        errors.push(`entry "${manifest.entry}" does not exist in the bundle`);
+    }
+    // v0.2 worlds embed system/ability CODE under helix_modules/ but never HELIX assets —
+    // those stream from the CDN. A clip/texture under helix_modules/ is a licensing leak.
+    if (manifest?.helixVersion === '0.2') {
+        const leaked = (0, helix_manifest_1.embeddedModuleAssets)(files.map((f) => f.path));
+        if (leaked.length) {
+            errors.push(`HELIX assets must stream from the CDN, not ship under helix_modules/: ${leaked.join(', ')}`);
+        }
+    }
+    return { manifest, files, errors };
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export type CliCredentials = {
+    apiUrl: string;
+    token: string;
+    expiresAt: string;
+    username: string;
+};
+export declare const DEFAULT_API_URL: string;
+export declare function saveCredentials(creds: CliCredentials): void;
+export declare function loadCredentials(): CliCredentials | null;
+export declare function clearCredentials(): void;
+export declare function jwtExpiresAtIso(token: string): string;

package/dist/config.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_URL = void 0;
+exports.saveCredentials = saveCredentials;
+exports.loadCredentials = loadCredentials;
+exports.clearCredentials = clearCredentials;
+exports.jwtExpiresAtIso = jwtExpiresAtIso;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const CONFIG_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.helix');
+const CREDENTIALS_FILE = (0, node_path_1.join)(CONFIG_DIR, 'credentials.json');
+exports.DEFAULT_API_URL = process.env.HELIX_API_URL ?? 'http://localhost:5000';
+function saveCredentials(creds) {
+    (0, node_fs_1.mkdirSync)(CONFIG_DIR, { recursive: true });
+    (0, node_fs_1.writeFileSync)(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), {
+        mode: 0o600,
+    });
+    try {
+        (0, node_fs_1.chmodSync)(CREDENTIALS_FILE, 0o600);
+    }
+    catch {
+        // Windows: mode bits are advisory; the file lives under the user profile.
+    }
+}
+function loadCredentials() {
+    try {
+        const creds = JSON.parse((0, node_fs_1.readFileSync)(CREDENTIALS_FILE, 'utf8'));
+        if (creds.expiresAt && new Date(creds.expiresAt).getTime() < Date.now()) {
+            return null;
+        }
+        return creds;
+    }
+    catch {
+        return null;
+    }
+}
+function clearCredentials() {
+    try {
+        (0, node_fs_1.writeFileSync)(CREDENTIALS_FILE, '{}', { mode: 0o600 });
+    }
+    catch {
+        // nothing stored — already logged out.
+    }
+}
+// Reads the `exp` (seconds) claim from a JWT without verifying its signature —
+// just to surface a friendly expiry to the user and to expire the stored
+// credentials locally. Returns '' if the token is not a decodable JWT.
+function jwtExpiresAtIso(token) {
+    try {
+        const payload = token.split('.')[1];
+        if (!payload)
+            return '';
+        const json = Buffer.from(payload, 'base64url').toString('utf8');
+        const exp = JSON.parse(json).exp;
+        return typeof exp === 'number' ? new Date(exp * 1000).toISOString() : '';
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAkBA,0CAUC;AAED,0CAYC;AAED,4CAMC;AAKD,0CAUC;AAjED,qCAA4E;AAC5E,qCAAkC;AAClC,yCAAiC;AAUjC,MAAM,UAAU,GAAG,IAAA,gBAAI,EAAC,IAAA,iBAAO,GAAE,EAAE,QAAQ,CAAC,CAAC;AAC7C,MAAM,gBAAgB,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;AAEjD,QAAA,eAAe,GAC1B,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,uBAAuB,CAAC;AAEvD,SAAgB,eAAe,CAAC,KAAqB;IACnD,IAAA,mBAAS,EAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,IAAA,uBAAa,EAAC,gBAAgB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QAC9D,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,IAAI,CAAC;QACH,IAAA,mBAAS,EAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;IAC5E,CAAC;AACH,CAAC;AAED,SAAgB,eAAe;IAC7B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CACtB,IAAA,sBAAY,EAAC,gBAAgB,EAAE,MAAM,CAAC,CACrB,CAAC;QACpB,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACxE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAgB,gBAAgB;IAC9B,IAAI,CAAC;QACH,IAAA,uBAAa,EAAC,gBAAgB,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;IACzC,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,yEAAyE;AACzE,uEAAuE;AACvE,SAAgB,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChE,MAAM,GAAG,GAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAsB,CAAC,GAAG,CAAC;QACvD,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};