@forgecart/cli 2.202610130131.0 → 2.202610130431.0

package/dist/src/authorization/cli-credential-step.d.ts

@@ -0,0 +1,74 @@
+import { type CliCredentials, type CliCredentialStepInput, type CliSettledCredentials } from './type/cli-authorization.types.js';
+/**
+ * Default shop API base, INCLUDING the mounted path. The API serves the shop
+ * GraphQL endpoint at `/shop-api` (`app/forgecart/src/main.ts`), and the SDK
+ * takes this value verbatim as its endpoint. The SDK swaps the scheme for the
+ * websocket and appends nothing to the path, so a pathless origin scaffolds a
+ * storefront whose every read dials a socket nothing answers (#2102): the
+ * operation rides graphql-ws's whole retry ladder and the page hangs with
+ * nothing logged. `init`'s `--api-url` defaults to it, and the credential step
+ * authorizes against its admin API when no source names an API.
+ */
+export declare const DEFAULT_SHOP_API_URL = "https://api.forgecart.com/shop-api";
+/**
+ * The ONE credential step (launch#62 N3). Every command that needs the four
+ * `FORGECART_*` keys reads them through this step. It looks for each key in
+ * the environment, then the storefront's `.env`, then its
+ * `.forgecart/config.json`.
+ *
+ * When a key is in no source, or the admin API refuses the credentials as one
+ * of the {@link CliCredentialRefusalCode} codes, the step authorizes this
+ * machine at `/authorize` with the project's store preselected. The four keys
+ * the approval delivers land in the storefront's `.env` the moment the poll
+ * delivers them, so a run that is interrupted afterwards keeps them and its
+ * re-run opens no browser. The command then continues on the delivered keys.
+ * A denial, an expiry or an elapsed wait exits 3 with
+ * FORGECART_CLI_UNAUTHORIZED and writes nothing. The step authorizes at most
+ * once per run: if the admin API refuses the credentials an approval has just
+ * delivered, the run exits 3 and never 1.
+ */
+export declare class CliCredentialStep {
+    private readonly input;
+    constructor(input: CliCredentialStepInput);
+    /**
+     * The four credentials the sources carry. When a key is in no source, the
+     * step returns the four an authorization delivers. Use this for a command
+     * that sends nothing to the admin API before its own work ends, as `init`
+     * does.
+     */
+    settle(): Promise<CliSettledCredentials>;
+    /**
+     * Run `command` on the settled credentials. If the admin API refuses the
+     * credentials the sources carried, the step authorizes this machine and runs
+     * `command` once more on the delivered keys. A refusal of keys an
+     * authorization delivered ends the run on exit 3.
+     */
+    run<T>(command: (credentials: CliCredentials) => Promise<T>): Promise<T>;
+    private settleFrom;
+    /**
+     * The command's run on the credentials the sources carry. The admin API
+     * refusing those credentials is the one failure that does not end the run:
+     * the step answers it by authorizing. Every other error propagates as
+     * thrown.
+     */
+    private runOnSourced;
+    /** Authorize this machine for the project's store, and keep what the approval delivers in `.env` at once. */
+    private authorize;
+    /** Why a run whose credentials were all found authorizes: the code the admin API refused them with. */
+    private refusalReport;
+    /**
+     * The admin API that answers the authorization. The step uses
+     * FORGECART_ADMIN_API_URL when a source names it. Otherwise it uses
+     * {@link ADMIN_API_PATH} on the origin of the caller's shop API, else the
+     * shop API the sources name, else the platform's.
+     */
+    private adminApiUrlOf;
+    /**
+     * Merge the four delivered keys into the storefront's `.env`. Each key is
+     * refreshed in place, and every other line is kept verbatim. The step
+     * creates the storefront directory if it does not exist yet.
+     */
+    private writeDotenv;
+    /** Read a file that may legitimately not exist yet. Any other failure propagates. */
+    private readIfPresent;
+}

package/dist/src/authorization/cli-credential-step.js

@@ -0,0 +1,154 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { print } from '../output.js';
+import { mergeDotenv } from '../util/dotenv.util.js';
+import { CliAuthorizationFlow } from './cli-authorization-flow.js';
+import { CliAuthorizationClient } from './cli-authorization.client.js';
+import { CliCredentialCheck } from './cli-credential-check.js';
+import { CliCredentialsRefusal } from './cli-unauthorized-refusal.js';
+import { CliCredentialKey, } from './type/cli-authorization.types.js';
+/**
+ * Default shop API base, INCLUDING the mounted path. The API serves the shop
+ * GraphQL endpoint at `/shop-api` (`app/forgecart/src/main.ts`), and the SDK
+ * takes this value verbatim as its endpoint. The SDK swaps the scheme for the
+ * websocket and appends nothing to the path, so a pathless origin scaffolds a
+ * storefront whose every read dials a socket nothing answers (#2102): the
+ * operation rides graphql-ws's whole retry ladder and the page hangs with
+ * nothing logged. `init`'s `--api-url` defaults to it, and the credential step
+ * authorizes against its admin API when no source names an API.
+ */
+export const DEFAULT_SHOP_API_URL = 'https://api.forgecart.com/shop-api';
+/**
+ * The admin API's path beside the shop API's on every platform origin: the
+ * server's `ADMIN_API_PATH`. When no FORGECART_ADMIN_API_URL names the admin
+ * API outright, the authorization is requested at this path on the shop API's
+ * origin (#2772, ruling R2).
+ */
+const ADMIN_API_PATH = '/admin-api';
+/**
+ * The ONE credential step (launch#62 N3). Every command that needs the four
+ * `FORGECART_*` keys reads them through this step. It looks for each key in
+ * the environment, then the storefront's `.env`, then its
+ * `.forgecart/config.json`.
+ *
+ * When a key is in no source, or the admin API refuses the credentials as one
+ * of the {@link CliCredentialRefusalCode} codes, the step authorizes this
+ * machine at `/authorize` with the project's store preselected. The four keys
+ * the approval delivers land in the storefront's `.env` the moment the poll
+ * delivers them, so a run that is interrupted afterwards keeps them and its
+ * re-run opens no browser. The command then continues on the delivered keys.
+ * A denial, an expiry or an elapsed wait exits 3 with
+ * FORGECART_CLI_UNAUTHORIZED and writes nothing. The step authorizes at most
+ * once per run: if the admin API refuses the credentials an approval has just
+ * delivered, the run exits 3 and never 1.
+ */
+export class CliCredentialStep {
+    input;
+    constructor(input) {
+        this.input = input;
+    }
+    /**
+     * The four credentials the sources carry. When a key is in no source, the
+     * step returns the four an authorization delivers. Use this for a command
+     * that sends nothing to the admin API before its own work ends, as `init`
+     * does.
+     */
+    async settle() {
+        return this.settleFrom(await CliCredentialCheck.read(this.input.targetDir));
+    }
+    /**
+     * Run `command` on the settled credentials. If the admin API refuses the
+     * credentials the sources carried, the step authorizes this machine and runs
+     * `command` once more on the delivered keys. A refusal of keys an
+     * authorization delivered ends the run on exit 3.
+     */
+    async run(command) {
+        const check = await CliCredentialCheck.read(this.input.targetDir);
+        const settled = await this.settleFrom(check);
+        if (settled.authorized)
+            return command(settled.credentials);
+        const sourced = await this.runOnSourced(command, settled.credentials);
+        if (!sourced.refused)
+            return sourced.result;
+        return command(await this.authorize(check, this.refusalReport(sourced.code)));
+    }
+    async settleFrom(check) {
+        const found = check.credentials();
+        if (found !== undefined)
+            return { credentials: found, authorized: false };
+        return { credentials: await this.authorize(check, check.report()), authorized: true };
+    }
+    /**
+     * The command's run on the credentials the sources carry. The admin API
+     * refusing those credentials is the one failure that does not end the run:
+     * the step answers it by authorizing. Every other error propagates as
+     * thrown.
+     */
+    async runOnSourced(command, credentials) {
+        try {
+            return { refused: false, result: await command(credentials) };
+        }
+        catch (error) {
+            if (error instanceof CliCredentialsRefusal)
+                return { refused: true, code: error.code };
+            throw error;
+        }
+    }
+    /** Authorize this machine for the project's store, and keep what the approval delivers in `.env` at once. */
+    async authorize(check, report) {
+        const client = new CliAuthorizationClient(this.adminApiUrlOf(check));
+        const flow = new CliAuthorizationFlow(client, this.input.timeoutSec);
+        const credentials = await flow.authorize(report, check.value(CliCredentialKey.CHANNEL_TOKEN));
+        await this.writeDotenv(credentials);
+        return credentials;
+    }
+    /** Why a run whose credentials were all found authorizes: the code the admin API refused them with. */
+    refusalReport(code) {
+        return ['', `  The admin API refused the credentials: ${code}.`];
+    }
+    /**
+     * The admin API that answers the authorization. The step uses
+     * FORGECART_ADMIN_API_URL when a source names it. Otherwise it uses
+     * {@link ADMIN_API_PATH} on the origin of the caller's shop API, else the
+     * shop API the sources name, else the platform's.
+     */
+    adminApiUrlOf(check) {
+        const named = check.value(CliCredentialKey.ADMIN_API_URL);
+        if (named !== undefined)
+            return named;
+        const shopApiUrl = this.input.shopApiUrl ?? check.value(CliCredentialKey.SHOP_API_URL) ?? DEFAULT_SHOP_API_URL;
+        if (!URL.canParse(shopApiUrl)) {
+            throw new Error(`${shopApiUrl} is not a URL, so the admin API to authorize against cannot be found.`);
+        }
+        return new URL(ADMIN_API_PATH, shopApiUrl).toString();
+    }
+    /**
+     * Merge the four delivered keys into the storefront's `.env`. Each key is
+     * refreshed in place, and every other line is kept verbatim. The step
+     * creates the storefront directory if it does not exist yet.
+     */
+    async writeDotenv(credentials) {
+        await mkdir(this.input.targetDir, { recursive: true });
+        const path = join(this.input.targetDir, '.env');
+        const managed = new Map([
+            [CliCredentialKey.CHANNEL_TOKEN, credentials.channelToken],
+            [CliCredentialKey.SHOP_API_URL, credentials.shopApiUrl],
+            [CliCredentialKey.ADMIN_SECRET, credentials.adminSecret],
+            [CliCredentialKey.ADMIN_API_URL, credentials.adminApiUrl],
+        ]);
+        await writeFile(path, mergeDotenv(await this.readIfPresent(path), managed), 'utf8');
+        print(`  ✓ Wrote the four FORGECART_* keys to ${path}`);
+    }
+    /** Read a file that may legitimately not exist yet. Any other failure propagates. */
+    async readIfPresent(path) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=cli-credential-step.js.map

package/dist/src/authorization/cli-credential-step.js.map

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

package/dist/src/authorization/cli-unauthorized-refusal.d.ts

@@ -1,4 +1,5 @@
 import { CliRefusal } from '../exit-ladder.js';
+import { CliCredentialRefusalCode } from './type/cli-authorization.types.js';
 /** The code a scripted caller routes on beside exit 3 — never the prose after it. */
 export declare const CLI_UNAUTHORIZED_CODE = "FORGECART_CLI_UNAUTHORIZED";
 /** Why no approval delivered the credentials. */
@@ -9,19 +10,28 @@ export declare enum CliUnauthorizedReason {
     EXPIRED = "expired",
     /** `--timeout` elapsed before an approval. */
     TIMED_OUT = "timed-out",
-    /** A command that never authorizes (`forgecart sync`, #2781) found a credential in no source. */
-    MISSING = "missing",
-    /** The admin API refused the credentials the run settled — UNAUTHORIZED or FORBIDDEN. */
+    /** The admin API refused the credentials the run settled, as one of {@link CliCredentialRefusalCode}. */
     REFUSED = "refused"
 }
 /**
- * Credentials a run cannot use — exit {@link CliExitLadder.unauthorized} with
- * {@link CLI_UNAUTHORIZED_CODE}, never a hang: an authorization that did not
- * end approved (#2772, record `refs/design/cli-improvements`,
- * `init?case=headless`), or, for a command that never authorizes, a credential
- * absent from every source or credentials the admin API refused (#2781).
+ * Credentials a run cannot use. It exits {@link CliExitLadder.unauthorized}
+ * with {@link CLI_UNAUTHORIZED_CODE} and never hangs. Either an authorization
+ * did not end approved (#2772, record `refs/design/cli-improvements`,
+ * `init?case=headless`), or the admin API refused the credentials an
+ * authorization had just delivered ({@link CliCredentialsRefusal}).
  */
 export declare class CliUnauthorizedRefusal extends CliRefusal {
     readonly reason: CliUnauthorizedReason;
     constructor(reason: CliUnauthorizedReason);
 }
+/**
+ * Credentials the admin API refused, with the code it refused them with. The
+ * credential step answers this refusal by authorizing this machine once
+ * (launch#62 N3). If the refusal reaches the run, the run exits 3 and never 1.
+ */
+export declare class CliCredentialsRefusal extends CliUnauthorizedRefusal {
+    readonly code: CliCredentialRefusalCode;
+    constructor(code: CliCredentialRefusalCode);
+    /** Whether the admin API refuses credentials with `code`. Every other code is a refusal of the operation. */
+    static isRefusalCode(code: string): code is CliCredentialRefusalCode;
+}

package/dist/src/authorization/cli-unauthorized-refusal.js

@@ -1,4 +1,5 @@
 import { CliExitLadder, CliRefusal } from '../exit-ladder.js';
+import { CliCredentialRefusalCode } from './type/cli-authorization.types.js';
 /** The code a scripted caller routes on beside exit 3 — never the prose after it. */
 export const CLI_UNAUTHORIZED_CODE = 'FORGECART_CLI_UNAUTHORIZED';
 /** Why no approval delivered the credentials. */
@@ -10,25 +11,22 @@ export var CliUnauthorizedReason;
     CliUnauthorizedReason["EXPIRED"] = "expired";
     /** `--timeout` elapsed before an approval. */
     CliUnauthorizedReason["TIMED_OUT"] = "timed-out";
-    /** A command that never authorizes (`forgecart sync`, #2781) found a credential in no source. */
-    CliUnauthorizedReason["MISSING"] = "missing";
-    /** The admin API refused the credentials the run settled — UNAUTHORIZED or FORBIDDEN. */
+    /** The admin API refused the credentials the run settled, as one of {@link CliCredentialRefusalCode}. */
     CliUnauthorizedReason["REFUSED"] = "refused";
 })(CliUnauthorizedReason || (CliUnauthorizedReason = {}));
-/** What each reason tells the merchant: what happened, that nothing was written, and the two ways on. */
+/** What each reason tells the merchant: what happened, what was written, and the two ways on. */
 const REASON_LINES = {
     [CliUnauthorizedReason.DENIED]: 'the authorization was denied at /authorize; nothing was written.',
     [CliUnauthorizedReason.EXPIRED]: 'the authorization window closed before an approval; nothing was written. Re-run to open a new one, or export the four FORGECART_* keys.',
     [CliUnauthorizedReason.TIMED_OUT]: 'no credentials in the environment, in .env or in .forgecart/config.json, and no approval within --timeout; nothing was written. Export the four FORGECART_* keys, or authorize at the URL above.',
-    [CliUnauthorizedReason.MISSING]: 'a credential is in none of the environment, .env and .forgecart/config.json, so nothing was sent. Export the four FORGECART_* keys, or run `forgecart init` to authorize this machine.',
-    [CliUnauthorizedReason.REFUSED]: 'the admin API refused the credentials; nothing was written. Export the four FORGECART_* keys of a channel admin, or run `forgecart init` to authorize this machine.',
+    [CliUnauthorizedReason.REFUSED]: 'the admin API refused the credentials. Export the four FORGECART_* keys of a channel admin, or re-run to authorize this machine at /authorize.',
 };
 /**
- * Credentials a run cannot use — exit {@link CliExitLadder.unauthorized} with
- * {@link CLI_UNAUTHORIZED_CODE}, never a hang: an authorization that did not
- * end approved (#2772, record `refs/design/cli-improvements`,
- * `init?case=headless`), or, for a command that never authorizes, a credential
- * absent from every source or credentials the admin API refused (#2781).
+ * Credentials a run cannot use. It exits {@link CliExitLadder.unauthorized}
+ * with {@link CLI_UNAUTHORIZED_CODE} and never hangs. Either an authorization
+ * did not end approved (#2772, record `refs/design/cli-improvements`,
+ * `init?case=headless`), or the admin API refused the credentials an
+ * authorization had just delivered ({@link CliCredentialsRefusal}).
  */
 export class CliUnauthorizedRefusal extends CliRefusal {
     reason;
@@ -38,4 +36,21 @@ export class CliUnauthorizedRefusal extends CliRefusal {
         this.name = 'CliUnauthorizedRefusal';
     }
 }
+/**
+ * Credentials the admin API refused, with the code it refused them with. The
+ * credential step answers this refusal by authorizing this machine once
+ * (launch#62 N3). If the refusal reaches the run, the run exits 3 and never 1.
+ */
+export class CliCredentialsRefusal extends CliUnauthorizedRefusal {
+    code;
+    constructor(code) {
+        super(CliUnauthorizedReason.REFUSED);
+        this.code = code;
+        this.name = 'CliCredentialsRefusal';
+    }
+    /** Whether the admin API refuses credentials with `code`. Every other code is a refusal of the operation. */
+    static isRefusalCode(code) {
+        return Object.values(CliCredentialRefusalCode).includes(code);
+    }
+}
 //# sourceMappingURL=cli-unauthorized-refusal.js.map

package/dist/src/authorization/cli-unauthorized-refusal.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-unauthorized-refusal.js","sourceRoot":"","sources":["../../../src/authorization/cli-unauthorized-refusal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE9D,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAC;AAElE,iDAAiD;AACjD,MAAM,CAAN,IAAY,qBAWX;AAXD,WAAY,qBAAqB;IAC/B,8DAA8D;IAC9D,0CAAiB,CAAA;IACjB,kFAAkF;IAClF,4CAAmB,CAAA;IACnB,8CAA8C;IAC9C,gDAAuB,CAAA;IACvB,iGAAiG;IACjG,4CAAmB,CAAA;IACnB,yFAAyF;IACzF,4CAAmB,CAAA;AACrB,CAAC,EAXW,qBAAqB,KAArB,qBAAqB,QAWhC;AAED,yGAAyG;AACzG,MAAM,YAAY,GAAoD;IACpE,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAC5B,kEAAkE;IACpE,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAC7B,yIAAyI;IAC3I,CAAC,qBAAqB,CAAC,SAAS,CAAC,EAC/B,kMAAkM;IACpM,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAC7B,wLAAwL;IAC1L,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAC7B,qKAAqK;CACxK,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IAC/B;IAArB,YAAqB,MAA6B;QAChD,KAAK,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC,GAAG,qBAAqB,MAAM,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QADvE,WAAM,GAAN,MAAM,CAAuB;QAEhD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"cli-unauthorized-refusal.js","sourceRoot":"","sources":["../../../src/authorization/cli-unauthorized-refusal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAE7E,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAC;AAElE,iDAAiD;AACjD,MAAM,CAAN,IAAY,qBASX;AATD,WAAY,qBAAqB;IAC/B,8DAA8D;IAC9D,0CAAiB,CAAA;IACjB,kFAAkF;IAClF,4CAAmB,CAAA;IACnB,8CAA8C;IAC9C,gDAAuB,CAAA;IACvB,yGAAyG;IACzG,4CAAmB,CAAA;AACrB,CAAC,EATW,qBAAqB,KAArB,qBAAqB,QAShC;AAED,iGAAiG;AACjG,MAAM,YAAY,GAAoD;IACpE,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAC5B,kEAAkE;IACpE,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAC7B,yIAAyI;IAC3I,CAAC,qBAAqB,CAAC,SAAS,CAAC,EAC/B,kMAAkM;IACpM,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAC7B,gJAAgJ;CACnJ,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IAC/B;IAArB,YAAqB,MAA6B;QAChD,KAAK,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC,GAAG,qBAAqB,MAAM,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QADvE,WAAM,GAAN,MAAM,CAAuB;QAEhD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,sBAAsB;IAC1C;IAArB,YAAqB,IAA8B;QACjD,KAAK,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QADlB,SAAI,GAAJ,IAAI,CAA0B;QAEjD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;IAED,6GAA6G;IAC7G,MAAM,CAAC,aAAa,CAAC,IAAY;QAC/B,OAAO,MAAM,CAAC,MAAM,CAAS,wBAAwB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxE,CAAC;CACF"}

package/dist/src/authorization/type/cli-authorization.types.d.ts

@@ -1,7 +1,6 @@
 /**
- * The four credentials a storefront runs on (#2772), by the `.env` key `init`
- * writes each one under — in the order the check names them and the merge
- * writes them.
+ * The four credentials a storefront runs on (#2772), each under the `.env` key
+ * the credential step writes it to, in the order the check names them.
  */
 export declare enum CliCredentialKey {
     CHANNEL_TOKEN = "FORGECART_CHANNEL_TOKEN",
@@ -30,10 +29,43 @@ export interface CliCredentials {
     shopApiUrl: string;
     adminApiUrl: string;
 }
-/** What `forgecart init` names when it opens an authorization: the machine, and itself. */
+/**
+ * The codes the admin API refuses an admin operation's credentials with, each
+ * of which runs the credential step (launch#62 N3): no grant for the request
+ * (UNAUTHORIZED, FORBIDDEN), an admin secret the channel no longer carries
+ * (INVALID_ADMIN_SECRET), and a channel token no store carries
+ * (CHANNEL_NOT_FOUND).
+ */
+export declare enum CliCredentialRefusalCode {
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    INVALID_ADMIN_SECRET = "INVALID_ADMIN_SECRET",
+    CHANNEL_NOT_FOUND = "CHANNEL_NOT_FOUND"
+}
+/** What the CLI names when it opens an authorization: the machine, itself, and the project's store. */
 export interface CliAuthorizationRequestInput {
     deviceName: string;
     cliVersion: string;
+    /** The channel token the project's sources name: the store `/authorize` preselects. Absent when they name none. */
+    channelToken?: string;
+}
+/** Where the credential step reads the four keys, where an approval writes them, and how long it waits for one. */
+export interface CliCredentialStepInput {
+    /** The storefront. The step reads its `.env` and `.forgecart/config.json`, and an approval's keys land in its `.env`. */
+    targetDir: string;
+    /**
+     * The shop API whose origin's admin API answers the authorization when no
+     * source names FORGECART_ADMIN_API_URL: `init`'s `--api-url`. When absent,
+     * the step uses the shop API the sources name, else the platform's.
+     */
+    shopApiUrl?: string;
+    /** The longest the wait for an approval may last, in seconds. When absent, the authorization's window bounds it. */
+    timeoutSec?: number;
+}
+/** The four credentials the step settled, and whether an approval in this run delivered them. */
+export interface CliSettledCredentials {
+    credentials: CliCredentials;
+    authorized: boolean;
 }
 /** The authorization the admin API opened, in the request result's wire shape. */
 export interface CliAuthorizationRequestResult {

package/dist/src/authorization/type/cli-authorization.types.js

@@ -1,7 +1,6 @@
 /**
- * The four credentials a storefront runs on (#2772), by the `.env` key `init`
- * writes each one under — in the order the check names them and the merge
- * writes them.
+ * The four credentials a storefront runs on (#2772), each under the `.env` key
+ * the credential step writes it to, in the order the check names them.
  */
 export var CliCredentialKey;
 (function (CliCredentialKey) {
@@ -21,4 +20,18 @@ export var CliAuthorizationState;
     CliAuthorizationState["DENIED"] = "DENIED";
     CliAuthorizationState["EXPIRED"] = "EXPIRED";
 })(CliAuthorizationState || (CliAuthorizationState = {}));
+/**
+ * The codes the admin API refuses an admin operation's credentials with, each
+ * of which runs the credential step (launch#62 N3): no grant for the request
+ * (UNAUTHORIZED, FORBIDDEN), an admin secret the channel no longer carries
+ * (INVALID_ADMIN_SECRET), and a channel token no store carries
+ * (CHANNEL_NOT_FOUND).
+ */
+export var CliCredentialRefusalCode;
+(function (CliCredentialRefusalCode) {
+    CliCredentialRefusalCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    CliCredentialRefusalCode["FORBIDDEN"] = "FORBIDDEN";
+    CliCredentialRefusalCode["INVALID_ADMIN_SECRET"] = "INVALID_ADMIN_SECRET";
+    CliCredentialRefusalCode["CHANNEL_NOT_FOUND"] = "CHANNEL_NOT_FOUND";
+})(CliCredentialRefusalCode || (CliCredentialRefusalCode = {}));
 //# sourceMappingURL=cli-authorization.types.js.map

package/dist/src/authorization/type/cli-authorization.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-authorization.types.js","sourceRoot":"","sources":["../../../../src/authorization/type/cli-authorization.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,6DAAyC,CAAA;IACzC,2DAAuC,CAAA;IACvC,2DAAuC,CAAA;IACvC,6DAAyC,CAAA;AAC3C,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,qBAKX;AALD,WAAY,qBAAqB;IAC/B,4CAAmB,CAAA;IACnB,8CAAqB,CAAA;IACrB,0CAAiB,CAAA;IACjB,4CAAmB,CAAA;AACrB,CAAC,EALW,qBAAqB,KAArB,qBAAqB,QAKhC"}
+{"version":3,"file":"cli-authorization.types.js","sourceRoot":"","sources":["../../../../src/authorization/type/cli-authorization.types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,6DAAyC,CAAA;IACzC,2DAAuC,CAAA;IACvC,2DAAuC,CAAA;IACvC,6DAAyC,CAAA;AAC3C,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,qBAKX;AALD,WAAY,qBAAqB;IAC/B,4CAAmB,CAAA;IACnB,8CAAqB,CAAA;IACrB,0CAAiB,CAAA;IACjB,4CAAmB,CAAA;AACrB,CAAC,EALW,qBAAqB,KAArB,qBAAqB,QAKhC;AAcD;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,wBAKX;AALD,WAAY,wBAAwB;IAClC,yDAA6B,CAAA;IAC7B,mDAAuB,CAAA;IACvB,yEAA6C,CAAA;IAC7C,mEAAuC,CAAA;AACzC,CAAC,EALW,wBAAwB,KAAxB,wBAAwB,QAKnC"}

package/dist/src/commands/init.d.ts

@@ -2,16 +2,6 @@ import { Command } from 'commander';
 import type { QuestionPromptInput } from '../question/type/question-prompt.input.js';
 import { TemplateSet } from '../template/template-set.js';
 import type { InitQuestionsInput } from './type/init.input.js';
-/**
- * Default shop API base, INCLUDING the mounted path. The API serves the shop
- * GraphQL endpoint at `/shop-api` (`app/forgecart/src/main.ts`), and the SDK
- * takes this value verbatim as its endpoint — it swaps the scheme for the
- * websocket and appends nothing to the path — so a pathless origin scaffolds a
- * storefront whose every read dials a socket nothing answers (#2102): the
- * operation rides graphql-ws's whole retry ladder and the page hangs with
- * nothing logged. Overridable via `--api-url`.
- */
-export declare const DEFAULT_SHOP_API_URL = "https://api.forgecart.com/shop-api";
 /**
  * Environment variable naming a dependency-warmed storefront template — a copy
  * of one bundled template with `node_modules` (and the generated

package/dist/src/commands/init.js

@@ -1,10 +1,7 @@
 import { mkdir, cp, readFile, rm, writeFile, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { Command, InvalidArgumentError, Option } from 'commander';
-import { CliAuthorizationFlow } from '../authorization/cli-authorization-flow.js';
-import { CliAuthorizationClient } from '../authorization/cli-authorization.client.js';
-import { CliCredentialCheck } from '../authorization/cli-credential-check.js';
-import { CliCredentialKey, } from '../authorization/type/cli-authorization.types.js';
+import { CliCredentialStep, DEFAULT_SHOP_API_URL } from '../authorization/cli-credential-step.js';
 import { print } from '../output.js';
 import { QuestionPromptAdapter } from '../question/question-prompt.adapter.js';
 import { TemplateSet } from '../template/template-set.js';
@@ -14,23 +11,6 @@ import { readPackageVersion } from '../version.js';
 import { stampDesignSystem, templateDesignSystem, } from './design-system-seat.js';
 import { InitQuestions } from './init-questions.js';
 import { inventoryTemplate, manifestTemplate, readTemplateManifest, serializeTemplateManifest, templateManifestPath, writeTemplateManifest, } from './template-manifest.js';
-/**
- * Default shop API base, INCLUDING the mounted path. The API serves the shop
- * GraphQL endpoint at `/shop-api` (`app/forgecart/src/main.ts`), and the SDK
- * takes this value verbatim as its endpoint — it swaps the scheme for the
- * websocket and appends nothing to the path — so a pathless origin scaffolds a
- * storefront whose every read dials a socket nothing answers (#2102): the
- * operation rides graphql-ws's whole retry ladder and the page hangs with
- * nothing logged. Overridable via `--api-url`.
- */
-export const DEFAULT_SHOP_API_URL = 'https://api.forgecart.com/shop-api';
-/**
- * The admin API's path beside the shop API's on every platform origin — the
- * server's `ADMIN_API_PATH`. With no FORGECART_ADMIN_API_URL to name the admin
- * API outright, the authorization is requested here on the `--api-url` origin
- * (#2772, ruling R2).
- */
-const ADMIN_API_PATH = '/admin-api';
 /**
  * Environment variable naming a dependency-warmed storefront template — a copy
  * of one bundled template with `node_modules` (and the generated
@@ -431,24 +411,27 @@ function printConfigOnly(targetDir, blank) {
 /**
  * Resolve the channel a run wires (#2772). `--token` is the pod's drive: its
  * flags are the whole configuration and nothing is checked. Otherwise the four
- * credentials are looked for — environment, `.env`, `.forgecart/config.json` —
- * and with all four found nothing is asked; with any absent the browser
- * authorization runs and its approval delivers all four. Nothing is written
- * before this resolves, so an authorization that ends unapproved leaves the
- * directory exactly as it found it.
+ * credentials come through the credential step (launch#62 N3), which looks for
+ * them in the environment, `.env` and `.forgecart/config.json`. With all four
+ * found, init asks nothing. With any absent, the browser authorization runs
+ * against the admin API of the `--api-url` origin, unless a source names
+ * FORGECART_ADMIN_API_URL. The four keys the approval delivers land in `.env`
+ * the moment the poll delivers them. A run that later ends at a question
+ * keeps them, and its re-run asks for no authorization. An authorization that
+ * ends unapproved writes nothing.
  */
 async function resolveChannelWiring(targetDir, options) {
     const token = options.token?.trim();
     if (token)
         return { channelToken: token, options, authorized: false };
     assertNoPodDriveFlags(options);
-    const check = await CliCredentialCheck.read(targetDir);
-    const found = check.credentials();
-    if (found)
-        return wiredWith(options, found, false);
-    const adminApiUrl = check.value(CliCredentialKey.ADMIN_API_URL) ?? adminApiOf(options.apiUrl);
-    const flow = new CliAuthorizationFlow(new CliAuthorizationClient(adminApiUrl));
-    return wiredWith(options, await flow.authorize(check.report(), options.timeout), true);
+    const step = new CliCredentialStep({
+        targetDir,
+        shopApiUrl: options.apiUrl,
+        timeoutSec: options.timeout,
+    });
+    const { credentials, authorized } = await step.settle();
+    return wiredWith(options, credentials, authorized);
 }
 /** The run's wiring once the four credentials are known: they take the seats of the flags they name. */
 function wiredWith(options, credentials, authorized) {
@@ -469,13 +452,6 @@ function assertNoPodDriveFlags(options) {
         return;
     throw new Error('--admin-secret and --admin-api-url belong to the pod drive beside --token. Export FORGECART_ADMIN_SECRET and FORGECART_ADMIN_API_URL instead, or let init authorize this machine in the browser.');
 }
-/** The admin API on the `--api-url` origin — the platform's fixed path pair (ruling R2). */
-function adminApiOf(apiUrl) {
-    if (!URL.canParse(apiUrl)) {
-        throw new Error(`--api-url ${apiUrl} is not a URL, so the admin API to authorize against cannot be found.`);
-    }
-    return new URL(ADMIN_API_PATH, apiUrl).toString();
-}
 /**
  * What an approval wrote, and where — printed on the run the approval landed in,
  * and only there. A blank workspace (#2775) renders no template, so no template
@@ -509,8 +485,7 @@ function printEnvCommitNote(blank) {
  * tree already has its template identity, and its config keeps the scaffold
  * record it carries and mirrors the design-system seat the workspace records
  * (#2773), settled first ({@link settleInPlaceDesignSystem}, #2808).
- * The channel is resolved before any of it is written
- * ({@link resolveChannelWiring}, #2772).
+ * The channel is resolved first ({@link resolveChannelWiring}, #2772).
  */
 async function configureInPlace(targetDir, options, manifest) {
     if (!(await isScaffolded(targetDir, manifest))) {