@forgecart/cli 2.202610102045.0 → 2.202610110825.0

package/dist/src/sync/workspace-sync.client.js

@@ -0,0 +1,317 @@
+import { createHash } from 'node:crypto';
+import { CliUnauthorizedReason, CliUnauthorizedRefusal, } from '../authorization/cli-unauthorized-refusal.js';
+import { isJsonObject } from '../json.js';
+import { SyncApiError } from './sync-api.error.js';
+/** The SDK's `WorkspaceSyncRetrieve` operation, verbatim. */
+const STATE_DOCUMENT = `query WorkspaceSyncRetrieve {
+  workspaceSyncState {
+    id
+    servingSha
+  }
+}`;
+/** The SDK's `WorkspaceSyncPull` operation, verbatim. */
+const BUNDLE_DOCUMENT = `query WorkspaceSyncPull($input: WorkspaceSyncBundleInput!) {
+  workspaceSyncBundle(input: $input) {
+    id
+    sinceSha
+    byteLength
+    sha256
+    data
+    envLines
+  }
+}`;
+/** The SDK's `WorkspaceSyncPush` operation, verbatim. */
+const PUSH_DOCUMENT = `mutation WorkspaceSyncPush($input: PushWorkspaceSyncInput!) {
+  pushWorkspaceSync(input: $input) {
+    id
+    accepted
+    servingSha
+    gateMessages
+    runtimeError
+    seoFindings
+    envKeys
+  }
+}`;
+/** The codes the admin API refuses an admin operation's credentials with. */
+const CREDENTIAL_REFUSALS = new Set(['UNAUTHORIZED', 'FORBIDDEN']);
+/** The multipart part a push's bundle travels in, and the variable it answers (GraphQL multipart request spec). */
+const BUNDLE_PART = '0';
+const BUNDLE_VARIABLE = 'variables.input.bundle';
+const BUNDLE_FILE_NAME = 'serving.bundle';
+/** Milliseconds in a second — `--timeout` is given in seconds. */
+const MS_PER_SECOND = 1000;
+/**
+ * The admin API's three workspace-sync operations (#2781), over GraphQL on
+ * HTTP with the channel token and the admin secret as the `forgecart-token` and
+ * `forgecart-secret` headers — the one surface `forgecart sync` reaches the
+ * shop through. Every request goes to FORGECART_ADMIN_API_URL as given, and
+ * every exchange is bounded by `--timeout` and ends when the run is
+ * interrupted. Answers are read field by field: one the CLI cannot read is an
+ * error naming the endpoint, never a guess. Credentials the API refuses end the
+ * run on exit 3; any other refusal is a {@link SyncApiError} carrying its code.
+ */
+export class WorkspaceSyncClient {
+    credentials;
+    timeoutSeconds;
+    interrupt;
+    /**
+     * @param credentials the four credentials the run settled.
+     * @param timeoutSeconds the bound on one exchange — `--timeout`.
+     * @param interrupt ends every exchange in flight when the run is interrupted.
+     */
+    constructor(credentials, timeoutSeconds, interrupt) {
+        this.credentials = credentials;
+        this.timeoutSeconds = timeoutSeconds;
+        this.interrupt = interrupt;
+    }
+    /** The board's serving commit, read from the pod. */
+    async state() {
+        const field = 'workspaceSyncState';
+        const result = await this.exchange(this.jsonRequest(STATE_DOCUMENT, {}), field);
+        return { servingSha: this.readString(result, 'servingSha', field) };
+    }
+    /**
+     * The serving branch since `sinceSha` — all of it for `''` — as ONE git
+     * bundle, checked against its declared byte length and sha256 before anything
+     * reads it: a short or mismatched bundle is an error, and nothing is written.
+     */
+    async bundle(sinceSha) {
+        const field = 'workspaceSyncBundle';
+        const result = await this.exchange(this.jsonRequest(BUNDLE_DOCUMENT, { input: { sinceSha } }), field);
+        const bytes = Buffer.from(this.readString(result, 'data', field), 'base64');
+        this.assertDeclared(bytes, this.readCount(result, 'byteLength', field), this.readString(result, 'sha256', field));
+        return {
+            sinceSha: this.readText(result, 'sinceSha', field),
+            bytes,
+            envLines: this.readStringList(result, 'envLines', field),
+        };
+    }
+    /**
+     * Push `bundle` — the laptop's tree as one commit cut on the serving tip — as
+     * an authenticated upload, with the merchant `.env` lines `envLines`; a push
+     * without a bundle carries the lines alone.
+     */
+    async push(bundle, envLines) {
+        const field = 'pushWorkspaceSync';
+        const result = await this.exchange(this.pushRequest(bundle, envLines), field);
+        return {
+            accepted: this.readBoolean(result, 'accepted', field),
+            servingSha: this.readNullableString(result, 'servingSha', field),
+            gateMessages: this.readStringList(result, 'gateMessages', field),
+            runtimeError: this.readNullableString(result, 'runtimeError', field),
+            seoFindings: this.readStringList(result, 'seoFindings', field),
+            envKeys: this.readCount(result, 'envKeys', field),
+        };
+    }
+    /** A push with a bundle is an upload; one with `.env` lines alone is plain JSON. */
+    pushRequest(bundle, envLines) {
+        if (bundle === null)
+            return this.jsonRequest(PUSH_DOCUMENT, { input: { envLines } });
+        return this.uploadRequest(bundle, envLines);
+    }
+    /** A GraphQL request as JSON. */
+    jsonRequest(document, variables) {
+        return {
+            body: JSON.stringify({ query: document, variables }),
+            headers: { ...this.authHeaders(), 'content-type': 'application/json' },
+        };
+    }
+    /**
+     * The push as a GraphQL multipart request: the operation, the map naming the
+     * bundle's variable, and the bundle itself, declared by its byte length and
+     * sha256. The admin API reads a multipart request only with the preflight
+     * header; the boundary is the form's own.
+     */
+    uploadRequest(bundle, envLines) {
+        const input = {
+            bundle: null,
+            byteLength: bundle.length,
+            sha256: createHash('sha256').update(bundle).digest('hex'),
+            envLines,
+        };
+        const form = new FormData();
+        form.append('operations', JSON.stringify({ query: PUSH_DOCUMENT, variables: { input } }));
+        form.append('map', JSON.stringify({ [BUNDLE_PART]: [BUNDLE_VARIABLE] }));
+        form.append(BUNDLE_PART, new Blob([new Uint8Array(bundle)]), BUNDLE_FILE_NAME);
+        return { body: form, headers: { ...this.authHeaders(), 'apollo-require-preflight': 'true' } };
+    }
+    authHeaders() {
+        return {
+            accept: 'application/json',
+            'forgecart-token': this.credentials.channelToken,
+            'forgecart-secret': this.credentials.adminSecret,
+        };
+    }
+    /**
+     * POST one operation and answer its root field's object. The exchange — the
+     * response and its whole body — is bounded by `--timeout` and ends with the
+     * run's interrupt.
+     */
+    async exchange(request, field) {
+        const bound = new AbortController();
+        const timer = setTimeout(() => {
+            bound.abort();
+        }, this.timeoutSeconds * MS_PER_SECOND);
+        const relay = () => {
+            bound.abort();
+        };
+        this.interrupt.addEventListener('abort', relay, { once: true });
+        try {
+            const { status, text } = await this.post(request, bound.signal, field);
+            return this.rootField(this.parseBody(text, status), field);
+        }
+        finally {
+            clearTimeout(timer);
+            this.interrupt.removeEventListener('abort', relay);
+        }
+    }
+    async post(request, signal, field) {
+        try {
+            const response = await fetch(this.credentials.adminApiUrl, {
+                method: 'POST',
+                headers: request.headers,
+                body: request.body,
+                signal,
+            });
+            return { status: response.status, text: await response.text() };
+        }
+        catch (error) {
+            throw this.exchangeFailure(error, signal, field);
+        }
+    }
+    /** Why an exchange ended without an answer: the run's interrupt, `--timeout`, or the network. */
+    exchangeFailure(error, signal, field) {
+        const endpoint = this.credentials.adminApiUrl;
+        if (this.interrupt.aborted) {
+            return new Error(`Interrupted while the admin API at ${endpoint} answered ${field}.`, {
+                cause: error,
+            });
+        }
+        if (signal.aborted) {
+            return new Error(`The admin API at ${endpoint} did not answer ${field} within --timeout ${String(this.timeoutSeconds)} s.`, { cause: error });
+        }
+        return new Error(`Could not reach the admin API at ${endpoint}: ${this.failureDetail(error)}.`, {
+            cause: error,
+        });
+    }
+    /** The response's GraphQL body — an answer that is not one names its HTTP status. */
+    parseBody(text, status) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(this.notGraphQlMessage(status), { cause: error });
+        }
+        if (!isJsonObject(parsed))
+            throw new Error(this.notGraphQlMessage(status));
+        return parsed;
+    }
+    /** The root field's object, once the body carries no error. */
+    rootField(body, field) {
+        this.assertNoErrors(body.errors, field);
+        const data = body.data;
+        const result = isJsonObject(data) ? data[field] : undefined;
+        if (!isJsonObject(result))
+            throw this.unreadable(field);
+        return result;
+    }
+    /**
+     * A GraphQL error ends the call: credentials refused as UNAUTHORIZED or
+     * FORBIDDEN on exit 3, any other code as the typed {@link SyncApiError}.
+     */
+    assertNoErrors(errors, field) {
+        if (!Array.isArray(errors) || errors.length === 0)
+            return;
+        const first = errors[0];
+        const extensions = this.extensionsOf(first);
+        const code = typeof extensions.code === 'string' ? extensions.code : undefined;
+        if (code !== undefined && CREDENTIAL_REFUSALS.has(code)) {
+            throw new CliUnauthorizedRefusal(CliUnauthorizedReason.REFUSED);
+        }
+        throw new SyncApiError(this.credentials.adminApiUrl, field, code ?? this.messageOf(first), this.errorVariables(extensions.variables));
+    }
+    extensionsOf(error) {
+        return isJsonObject(error) && isJsonObject(error.extensions) ? error.extensions : {};
+    }
+    messageOf(error) {
+        return isJsonObject(error) && typeof error.message === 'string' ? error.message : '';
+    }
+    /** The variables a typed error carries, as text — none when it carries none. */
+    errorVariables(variables) {
+        if (!isJsonObject(variables))
+            return {};
+        return Object.fromEntries(Object.entries(variables).map(([key, value]) => [
+            key,
+            typeof value === 'string' ? value : JSON.stringify(value),
+        ]));
+    }
+    /** A pulled bundle's bytes against what it declares: its length, then its sha256. */
+    assertDeclared(bytes, byteLength, sha256) {
+        if (bytes.length !== byteLength) {
+            throw new Error(`The pulled bundle is ${String(bytes.length)} bytes, not the ${String(byteLength)} it declares; nothing was written.`);
+        }
+        if (createHash('sha256').update(bytes).digest('hex') !== sha256) {
+            throw new Error('The pulled bundle does not hash to the sha256 it declares; nothing was written.');
+        }
+    }
+    /** A string field that must carry text. */
+    readString(record, key, field) {
+        const value = record[key];
+        if (typeof value !== 'string' || value === '')
+            throw this.unreadable(field);
+        return value;
+    }
+    /** A string field that may be empty. */
+    readText(record, key, field) {
+        const value = record[key];
+        if (typeof value !== 'string')
+            throw this.unreadable(field);
+        return value;
+    }
+    readNullableString(record, key, field) {
+        const value = record[key];
+        if (value === null)
+            return null;
+        if (typeof value !== 'string')
+            throw this.unreadable(field);
+        return value;
+    }
+    readStringList(record, key, field) {
+        const value = record[key];
+        if (!Array.isArray(value))
+            throw this.unreadable(field);
+        const items = value;
+        if (!items.every((item) => typeof item === 'string')) {
+            throw this.unreadable(field);
+        }
+        return items;
+    }
+    readCount(record, key, field) {
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+            throw this.unreadable(field);
+        }
+        return value;
+    }
+    readBoolean(record, key, field) {
+        const value = record[key];
+        if (typeof value !== 'boolean')
+            throw this.unreadable(field);
+        return value;
+    }
+    unreadable(field) {
+        return new Error(`The admin API at ${this.credentials.adminApiUrl} answered a ${field} result the CLI cannot read.`);
+    }
+    notGraphQlMessage(status) {
+        return `The admin API at ${this.credentials.adminApiUrl} answered HTTP ${String(status)} without a GraphQL response.`;
+    }
+    /** What failed to connect: fetch's own message names nothing, its cause names the socket error. */
+    failureDetail(error) {
+        const cause = error instanceof Error ? error.cause : undefined;
+        if (cause instanceof Error)
+            return cause.message;
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+//# sourceMappingURL=workspace-sync.client.js.map

package/dist/src/sync/workspace-sync.client.js.map

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

package/dist/src/util/dotenv.util.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `.env` rules a storefront's `.env` is written and read by (#1123, #2781):
+ * init's merge — the keys a run manages refreshed in place, every other line
+ * verbatim — and the split `forgecart sync` carries `.env` by: the platform's
+ * own `FORGECART_*` keys, which init writes and which never cross between a
+ * laptop and its workspace, against the merchant's keys, which do.
+ */
+/** The key `line` assigns — undefined for a comment, a blank or any other line. */
+export declare function dotenvKey(line: string): string | undefined;
+/** Whether `key` is the platform's — init's to write, never a merchant's to carry. */
+export declare function isPlatformKey(key: string): boolean;
+/** The value an assignment line assigns `key`: everything after its `=`, verbatim. */
+export declare function dotenvValue(line: string, key: string): string;
+/**
+ * The merchant's assignments among `lines`: the FIRST line of every key that is
+ * no platform key — the line init's merge refreshes — keyed by it, in order.
+ */
+export declare function merchantAssignments(lines: readonly string[]): Map<string, string>;
+/**
+ * Merge the `managed` keys into an `existing` `.env`, preserving every other
+ * line — merchant keys, comments, ordering — verbatim (#1123: a wholesale
+ * rewrite wiped the demo store's DEMO_* config on three provisioning drives).
+ * A managed key is refreshed in place at its existing position; its duplicates
+ * collapse onto the first occurrence; a managed key with no existing line is
+ * appended in the map's order. Trailing blank lines normalize to the single
+ * final newline. An empty `existing` renders the managed keys alone.
+ */
+export declare function mergeDotenv(existing: string, managed: ReadonlyMap<string, string>): string;

package/dist/src/util/dotenv.util.js

@@ -0,0 +1,81 @@
+/**
+ * The `.env` rules a storefront's `.env` is written and read by (#1123, #2781):
+ * init's merge — the keys a run manages refreshed in place, every other line
+ * verbatim — and the split `forgecart sync` carries `.env` by: the platform's
+ * own `FORGECART_*` keys, which init writes and which never cross between a
+ * laptop and its workspace, against the merchant's keys, which do.
+ */
+/** An assignment line: its key, then `=`. A line of any other shape is carried verbatim and never travels. */
+const ASSIGNMENT = /^([A-Za-z_]\w*)=/;
+/** The prefix every platform-owned key carries. */
+const PLATFORM_KEY_PREFIX = 'FORGECART_';
+/** The key `line` assigns — undefined for a comment, a blank or any other line. */
+export function dotenvKey(line) {
+    return ASSIGNMENT.exec(line)?.[1];
+}
+/** Whether `key` is the platform's — init's to write, never a merchant's to carry. */
+export function isPlatformKey(key) {
+    return key.startsWith(PLATFORM_KEY_PREFIX);
+}
+/** The value an assignment line assigns `key`: everything after its `=`, verbatim. */
+export function dotenvValue(line, key) {
+    return line.slice(key.length + 1);
+}
+/**
+ * The merchant's assignments among `lines`: the FIRST line of every key that is
+ * no platform key — the line init's merge refreshes — keyed by it, in order.
+ */
+export function merchantAssignments(lines) {
+    const assignments = new Map();
+    for (const line of lines) {
+        const key = dotenvKey(line);
+        if (key === undefined || isPlatformKey(key) || assignments.has(key))
+            continue;
+        assignments.set(key, line);
+    }
+    return assignments;
+}
+/**
+ * Merge the `managed` keys into an `existing` `.env`, preserving every other
+ * line — merchant keys, comments, ordering — verbatim (#1123: a wholesale
+ * rewrite wiped the demo store's DEMO_* config on three provisioning drives).
+ * A managed key is refreshed in place at its existing position; its duplicates
+ * collapse onto the first occurrence; a managed key with no existing line is
+ * appended in the map's order. Trailing blank lines normalize to the single
+ * final newline. An empty `existing` renders the managed keys alone.
+ */
+export function mergeDotenv(existing, managed) {
+    const refreshed = new Set();
+    const merged = existing.split('\n').flatMap((line) => refreshLine(line, managed, refreshed));
+    trimTrailingBlanks(merged);
+    for (const [key, value] of managed) {
+        if (!refreshed.has(key))
+            merged.push(`${key}=${value}`);
+    }
+    merged.push('');
+    return merged.join('\n');
+}
+/**
+ * One existing line through the merge: a line no managed key assigns passes
+ * through verbatim, a managed key refreshes in place on first sight, and its
+ * later duplicates drop.
+ */
+function refreshLine(line, managed, refreshed) {
+    const key = dotenvKey(line);
+    if (key === undefined)
+        return [line];
+    const value = managed.get(key);
+    if (value === undefined)
+        return [line];
+    if (refreshed.has(key))
+        return [];
+    refreshed.add(key);
+    return [`${key}=${value}`];
+}
+/** Drop the blank lines a file ends on: the merge writes exactly one final newline. */
+function trimTrailingBlanks(lines) {
+    while (lines.length > 0 && lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+}
+//# sourceMappingURL=dotenv.util.js.map

package/dist/src/util/dotenv.util.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202610102045.0",
+  "version": "2.202610110825.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {