@forgecart/cli 2.202610102045.0 → 2.202610110825.0

package/dist/src/sync/sync.runner.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { mkdir, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { CliCredentialCheck } from '../authorization/cli-credential-check.js';
+import { CliUnauthorizedReason, CliUnauthorizedRefusal, } from '../authorization/cli-unauthorized-refusal.js';
+import { print } from '../output.js';
+import { QuestionPromptAdapter } from '../question/question-prompt.adapter.js';
+import { SyncDivergenceSelection } from './sync-divergence.js';
+import { SyncDotenvFile } from './sync-dotenv.file.js';
+import { SyncRecordFile } from './sync-record.file.js';
+import { SyncRepository } from './sync-repository.js';
+import { SyncRound } from './sync-round.js';
+import { SyncWatch } from './sync-watch.js';
+import { WorkspaceSyncClient } from './workspace-sync.client.js';
+/**
+ * `forgecart sync [name]` (#2781): keep the storefront's tree and the board's
+ * serving tree the same tree. Before anything leaves the machine the run
+ * settles its four credentials — the environment, then the storefront's `.env`,
+ * then its `.forgecart/config.json`, exactly as `init` reads them; a key in no
+ * source exits 3 with nothing sent — and needs `git` on the PATH. Then it runs
+ * ONE round, or, with `--watch`, a round whenever a side moves until Ctrl-C.
+ */
+export class SyncRunner {
+    name;
+    options;
+    /**
+     * @param name the storefront directory as given — the current directory when absent.
+     * @param options the run's flags.
+     */
+    constructor(name, options) {
+        this.name = name;
+        this.options = options;
+    }
+    async run() {
+        this.assertFlags();
+        const storefront = this.name ? resolve(process.cwd(), this.name) : process.cwd();
+        const credentials = await this.settleCredentials(storefront);
+        await SyncRepository.assertGitOnPath();
+        await this.assertStorefront(storefront);
+        if (this.options.watch === true) {
+            await this.watch(storefront, credentials);
+            return;
+        }
+        const { round } = this.assemble(storefront, credentials, new AbortController().signal);
+        await round.run();
+    }
+    /** `--dry-run` plans one round and moves nothing; it cannot watch. */
+    assertFlags() {
+        if (this.options.dryRun !== true || this.options.watch !== true)
+            return;
+        throw new Error('--dry-run plans one round and moves nothing, so it cannot --watch.');
+    }
+    /**
+     * The four credentials, from the first source carrying each. With one in no
+     * source the run prints where it looked — key names, never values — and exits
+     * 3 before any request.
+     */
+    async settleCredentials(storefront) {
+        const check = await CliCredentialCheck.read(storefront);
+        const credentials = check.credentials();
+        if (credentials !== undefined)
+            return credentials;
+        for (const line of check.report())
+            print(line);
+        throw new CliUnauthorizedRefusal(CliUnauthorizedReason.MISSING);
+    }
+    /** The storefront must be a directory — `--pull` makes a new one to take the workspace's tree into. */
+    async assertStorefront(storefront) {
+        if (await this.isDirectory(storefront))
+            return;
+        if (this.options.pull === true) {
+            await mkdir(storefront, { recursive: true });
+            return;
+        }
+        throw new Error(`No storefront at ${storefront}: name an existing directory, or pass --pull to take the workspace's tree into a new one.`);
+    }
+    /** Watch until Ctrl-C, which ends the run in flight and prints where it stood. */
+    async watch(storefront, credentials) {
+        const interrupt = new AbortController();
+        const { client, repository, round } = this.assemble(storefront, credentials, interrupt.signal);
+        const watch = new SyncWatch(this.displayName(), round, repository, client);
+        const stop = () => {
+            interrupt.abort();
+        };
+        process.once('SIGINT', stop);
+        try {
+            await watch.run(interrupt.signal);
+        }
+        finally {
+            process.off('SIGINT', stop);
+        }
+    }
+    assemble(storefront, credentials, interrupt) {
+        const pullOnly = this.options.pull === true;
+        const client = new WorkspaceSyncClient(credentials, this.options.timeout, interrupt);
+        const repository = new SyncRepository(storefront);
+        const round = new SyncRound({ storefront: this.displayName(), pullOnly, dryRun: this.options.dryRun === true }, credentials, client, repository, new SyncRecordFile(storefront, this.channelOf(credentials)), new SyncDotenvFile(storefront), new SyncDivergenceSelection(new QuestionPromptAdapter(this.options), pullOnly));
+        return { client, repository, round };
+    }
+    /** The channel a record belongs to: a digest of the admin API and the channel token — never the token. */
+    channelOf(credentials) {
+        return createHash('sha256')
+            .update(`${credentials.adminApiUrl}\n${credentials.channelToken}`)
+            .digest('hex');
+    }
+    /** The storefront as the merchant named it. */
+    displayName() {
+        return this.name ?? '.';
+    }
+    async isDirectory(path) {
+        try {
+            return (await stat(path)).isDirectory();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=sync.runner.js.map

package/dist/src/sync/sync.runner.js.map

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

package/dist/src/sync/type/sync.types.d.ts

@@ -0,0 +1,159 @@
+import type { QuestionPromptInput } from '../../question/type/question-prompt.input.js';
+/**
+ * `forgecart sync`'s options as commander parses them (#2781), beside the three
+ * flags every questioning command carries — they answer the divergence
+ * selection. No option carries a token, a secret or a URL: the credentials are
+ * the four `FORGECART_*` keys the credential check settles.
+ */
+export interface SyncOptions extends QuestionPromptInput {
+    /** `--pull`: take the workspace's tree onto this laptop; never push. */
+    pull?: boolean;
+    /** `--watch`: keep syncing — push local edits, pull workspace landings — until interrupted. */
+    watch?: boolean;
+    /** `--dry-run`: print the plan and the paths a push would send; move nothing. */
+    dryRun?: boolean;
+    /** `--timeout <seconds>`: the longest one exchange with the admin API may take. */
+    timeout: number;
+}
+/** `forgecart sync-env`'s option: merge instead of read. */
+export interface SyncEnvOptions {
+    merge?: boolean;
+}
+/** What `forgecart sync-env` answers — the report the admin API parses. */
+export interface SyncEnvReport {
+    /** The merchant lines of the storefront's `.env` once the run is done. */
+    lines: string[];
+    /** How many merchant keys a merge carried in; 0 for a read. */
+    merged: number;
+}
+/** The board's serving branch, as the admin API reads it from the pod. */
+export interface SyncServingState {
+    servingSha: string;
+}
+/** A pulled bundle whose bytes matched their declared length and sha256. */
+export interface SyncPulledBundle {
+    /** The commit it is cut from; empty for the whole board. */
+    sinceSha: string;
+    bytes: Buffer;
+    /** The merchant lines of the workspace's `.env`. */
+    envLines: string[];
+}
+/** What the admin API answered a push. */
+export interface SyncPushResult {
+    accepted: boolean;
+    servingSha: string | null;
+    gateMessages: string[];
+    runtimeError: string | null;
+    seoFindings: string[];
+    envKeys: number;
+}
+/**
+ * The last sync, recorded under `.forgecart/sync/`: the channel it was against,
+ * the serving commit the laptop's tree last matched, and a digest of every
+ * merchant `.env` line as it last travelled.
+ */
+export interface SyncRecord {
+    channel: string;
+    servingSha: string;
+    env: Record<string, string>;
+}
+/** How a path differs between two trees (`git diff-tree`'s status letters). */
+export declare enum SyncChangeKind {
+    ADDED = "A",
+    DELETED = "D",
+    MODIFIED = "M",
+    TYPE_CHANGED = "T"
+}
+/** One path a change between two trees touches. */
+export interface SyncTreeChange {
+    kind: SyncChangeKind;
+    path: string;
+}
+/** What writing a tree onto the laptop did. */
+export interface SyncMaterialized {
+    written: number;
+    removed: number;
+}
+/**
+ * The serving branch, held in the private repository: its commit, the tree of
+ * it that travels, and the merchant `.env` lines its bundle carried — null when
+ * the commit was already held and no bundle was read.
+ */
+export interface SyncServing {
+    sha: string;
+    tree: string;
+    envLines: string[] | null;
+}
+/** A round's view: the record, and the three trees it compares. */
+export interface SyncView {
+    record: SyncRecord | null;
+    /** The travelling tree of the recorded base — the empty tree for a first sync. */
+    base: string;
+    local: string;
+    serving: SyncServing;
+    /** The paths each side changed since the base. */
+    localChanges: SyncTreeChange[];
+    workspaceChanges: SyncTreeChange[];
+}
+/** Where a round left the laptop: its tree, the serving commit it stands on, and the round in words. */
+export interface SyncRoundEnd {
+    localTree: string;
+    servingSha: string;
+    summary: string;
+}
+/** What a round decides from its view. */
+export declare enum SyncVerdict {
+    /** The laptop's tree is the serving tree. */
+    IN_SYNC = "in-sync",
+    /** Only the workspace changed: its tree is written onto the laptop. */
+    PULL = "pull",
+    /** Only the laptop changed: its tree lands on the serving tip. */
+    PUSH = "push",
+    /** Only the laptop changed, and the run never pushes (`--pull`). */
+    KEEP_LOCAL = "keep-local",
+    /** Both changed: the selection decides which tree wins. */
+    DIVERGED = "diverged"
+}
+/** One attempt of a round: settled, or a push the board moved past while it landed. */
+export type SyncAttempt = {
+    kind: 'settled';
+    end: SyncRoundEnd;
+} | {
+    kind: 'moved';
+    point: SyncDivergencePoint;
+};
+/** The `.env` lines a round sent alone: how many keys the workspace merged, and the digests to record. */
+export interface SyncSentEnv {
+    merged: number;
+    digests: Record<string, string>;
+}
+/** What one round needs to know of its run. */
+export interface SyncRoundOptions {
+    /** The storefront directory, as the run names it. */
+    storefront: string;
+    /** `--pull`: the round never pushes. */
+    pullOnly: boolean;
+    /** `--dry-run`: the round plans and moves nothing. */
+    dryRun: boolean;
+}
+/** The merchant `.env` lines a push carries, and the digests the record takes once they landed. */
+export interface SyncOutgoingEnv {
+    lines: string[];
+    digests: Record<string, string>;
+}
+/** What taking the workspace's `.env` lines did: the keys taken, and the digests the record takes. */
+export interface SyncTakenEnv {
+    taken: number;
+    digests: Record<string, string>;
+}
+/** The selection a divergence asks: which tree overrides the other, or neither. */
+export declare enum SyncDivergenceChoice {
+    LOCAL = "local",
+    WORKSPACE = "workspace",
+    ABORT = "abort"
+}
+/** Where a divergence left both sides: the laptop's tree and the serving commit it diverged from. */
+export interface SyncDivergencePoint {
+    localTree: string;
+    servingSha: string;
+}

package/dist/src/sync/type/sync.types.js

@@ -0,0 +1,30 @@
+/** How a path differs between two trees (`git diff-tree`'s status letters). */
+export var SyncChangeKind;
+(function (SyncChangeKind) {
+    SyncChangeKind["ADDED"] = "A";
+    SyncChangeKind["DELETED"] = "D";
+    SyncChangeKind["MODIFIED"] = "M";
+    SyncChangeKind["TYPE_CHANGED"] = "T";
+})(SyncChangeKind || (SyncChangeKind = {}));
+/** What a round decides from its view. */
+export var SyncVerdict;
+(function (SyncVerdict) {
+    /** The laptop's tree is the serving tree. */
+    SyncVerdict["IN_SYNC"] = "in-sync";
+    /** Only the workspace changed: its tree is written onto the laptop. */
+    SyncVerdict["PULL"] = "pull";
+    /** Only the laptop changed: its tree lands on the serving tip. */
+    SyncVerdict["PUSH"] = "push";
+    /** Only the laptop changed, and the run never pushes (`--pull`). */
+    SyncVerdict["KEEP_LOCAL"] = "keep-local";
+    /** Both changed: the selection decides which tree wins. */
+    SyncVerdict["DIVERGED"] = "diverged";
+})(SyncVerdict || (SyncVerdict = {}));
+/** The selection a divergence asks: which tree overrides the other, or neither. */
+export var SyncDivergenceChoice;
+(function (SyncDivergenceChoice) {
+    SyncDivergenceChoice["LOCAL"] = "local";
+    SyncDivergenceChoice["WORKSPACE"] = "workspace";
+    SyncDivergenceChoice["ABORT"] = "abort";
+})(SyncDivergenceChoice || (SyncDivergenceChoice = {}));
+//# sourceMappingURL=sync.types.js.map

package/dist/src/sync/type/sync.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.types.js","sourceRoot":"","sources":["../../../../src/sync/type/sync.types.ts"],"names":[],"mappings":"AAmEA,+EAA+E;AAC/E,MAAM,CAAN,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,6BAAW,CAAA;IACX,+BAAa,CAAA;IACb,gCAAc,CAAA;IACd,oCAAkB,CAAA;AACpB,CAAC,EALW,cAAc,KAAd,cAAc,QAKzB;AA4CD,0CAA0C;AAC1C,MAAM,CAAN,IAAY,WAWX;AAXD,WAAY,WAAW;IACrB,6CAA6C;IAC7C,kCAAmB,CAAA;IACnB,uEAAuE;IACvE,4BAAa,CAAA;IACb,kEAAkE;IAClE,4BAAa,CAAA;IACb,oEAAoE;IACpE,wCAAyB,CAAA;IACzB,2DAA2D;IAC3D,oCAAqB,CAAA;AACvB,CAAC,EAXW,WAAW,KAAX,WAAW,QAWtB;AAmCD,mFAAmF;AACnF,MAAM,CAAN,IAAY,oBAIX;AAJD,WAAY,oBAAoB;IAC9B,uCAAe,CAAA;IACf,+CAAuB,CAAA;IACvB,uCAAe,CAAA;AACjB,CAAC,EAJW,oBAAoB,KAApB,oBAAoB,QAI/B"}

package/dist/src/sync/workspace-sync.client.d.ts

@@ -0,0 +1,85 @@
+import type { CliCredentials } from '../authorization/type/cli-authorization.types.js';
+import type { SyncPulledBundle, SyncPushResult, SyncServingState } from './type/sync.types.js';
+/**
+ * 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 declare class WorkspaceSyncClient {
+    private readonly credentials;
+    private readonly timeoutSeconds;
+    private readonly 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: CliCredentials, timeoutSeconds: number, interrupt: AbortSignal);
+    /** The board's serving commit, read from the pod. */
+    state(): Promise<SyncServingState>;
+    /**
+     * 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.
+     */
+    bundle(sinceSha: string): Promise<SyncPulledBundle>;
+    /**
+     * 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.
+     */
+    push(bundle: Buffer | null, envLines: readonly string[]): Promise<SyncPushResult>;
+    /** A push with a bundle is an upload; one with `.env` lines alone is plain JSON. */
+    private pushRequest;
+    /** A GraphQL request as JSON. */
+    private jsonRequest;
+    /**
+     * 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.
+     */
+    private uploadRequest;
+    private authHeaders;
+    /**
+     * 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.
+     */
+    private exchange;
+    private post;
+    /** Why an exchange ended without an answer: the run's interrupt, `--timeout`, or the network. */
+    private exchangeFailure;
+    /** The response's GraphQL body — an answer that is not one names its HTTP status. */
+    private parseBody;
+    /** The root field's object, once the body carries no error. */
+    private rootField;
+    /**
+     * A GraphQL error ends the call: credentials refused as UNAUTHORIZED or
+     * FORBIDDEN on exit 3, any other code as the typed {@link SyncApiError}.
+     */
+    private assertNoErrors;
+    private extensionsOf;
+    private messageOf;
+    /** The variables a typed error carries, as text — none when it carries none. */
+    private errorVariables;
+    /** A pulled bundle's bytes against what it declares: its length, then its sha256. */
+    private assertDeclared;
+    /** A string field that must carry text. */
+    private readString;
+    /** A string field that may be empty. */
+    private readText;
+    private readNullableString;
+    private readStringList;
+    private readCount;
+    private readBoolean;
+    private unreadable;
+    private notGraphQlMessage;
+    /** What failed to connect: fetch's own message names nothing, its cause names the socket error. */
+    private failureDetail;
+}