@glasstrace/sdk 0.14.2 → 0.16.0

package/dist/cli/init.d.cts

@@ -9,6 +9,14 @@ interface InitOptions {
     projectRoot: string;
     yes: boolean;
     coverageMap: boolean;
+    /**
+     * When true, skip interactive confirmation and overwrite existing
+     * MCP configuration files without prompting. Preservation of the
+     * anonymous key, config cache, and developer API key still applies
+     * regardless of this flag — `--force` only affects the MCP diff
+     * prompt (DISC-1247 Scenario 2c). Defaults to `false`.
+     */
+    force?: boolean;
 }
 /** Result of running the init command. */
 interface InitResult {
@@ -17,6 +25,30 @@ interface InitResult {
     warnings: string[];
     errors: string[];
 }
+/**
+ * Decides whether the MCP config at `configPath` should be overwritten
+ * during re-init. Returns the action to take.
+ *
+ * - `"write"` — file does not exist, or existing content already matches
+ *   the expected content. Safe to write.
+ * - `"skip"` — existing file differs AND the user chose to keep it, or
+ *   we are in a non-interactive environment without `--force`.
+ * - `"force-overwrite"` — `force === true` (or user accepted the prompt)
+ *   and content differs; overwrite.
+ *
+ * The prompt is skipped entirely when `force` is true (non-interactive
+ * overwrite) or when there is no existing file / content already matches.
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function decideMcpConfigAction(options: {
+    configPath: string | null;
+    expectedContent: string;
+    force: boolean;
+    readFile?: (p: string) => string;
+    existsSync?: (p: string) => boolean;
+    prompt?: (question: string, defaultValue: boolean) => Promise<boolean>;
+}): Promise<"write" | "skip" | "force-overwrite">;
 /**
  * Identifies a scaffolding step that can be reversed during rollback.
  * Steps are tracked in execution order and rolled back in reverse.
@@ -29,6 +61,15 @@ type CompletedStep = "instrumentation" | "next-config" | "env-local" | "gitignor
  */
 interface RollbackState {
     steps: CompletedStep[];
+    /**
+     * Absolute path of the instrumentation file that the scaffolder
+     * wrote to. May be either `{root}/instrumentation.ts` or
+     * `{root}/src/instrumentation.ts` depending on the project layout
+     * (DISC-493 Issue 1). When absent, rollback falls back to the
+     * root path for backward compatibility with callers that do not
+     * populate this field.
+     */
+    instrumentationPath?: string;
     /** Original instrumentation.ts content saved before injection.
      *  When present, rollback restores this instead of using removeRegisterGlasstrace. */
     originalInstrumentationContent?: string;
@@ -46,5 +87,49 @@ declare function rollbackSteps(steps: CompletedStep[], projectRoot: string, stat
  * bottom calls this function and translates the result to process.exit().
  */
 declare function runInit(options: InitOptions): Promise<InitResult>;
+/**
+ * Outcome of {@link verifyAnonKeyRegistration}:
+ *
+ * - `"verified"` — the server registered the anon key (HTTP 2xx with a
+ *   schema-valid response body).
+ * - `"skipped"` — no anon key was on disk, so no verification request
+ *   was sent. Typically means MCP auto-configuration failed earlier
+ *   (warnings were already emitted) — distinct from a verification
+ *   success.
+ * - `"failed"` — the verification request was sent and failed.
+ *   `error` is a user-facing message distinguishing the failure class
+ *   (`fetch failed: ...`, `server rejected the key ...`, or
+ *   `server returned malformed response ...`) with no anon key bytes.
+ */
+type VerifyAnonKeyOutcome = {
+    outcome: "verified";
+} | {
+    outcome: "skipped";
+} | {
+    outcome: "failed";
+    error: string;
+};
+/**
+ * Verifies that the anonymous key written by init is registered
+ * server-side. Called at the end of the scaffold flow so that when it
+ * fails, the user sees an actionable error rather than a misleading
+ * "initialized successfully" followed by silent MCP authentication
+ * failures (DISC-494).
+ *
+ * Returns a discriminated outcome so the CLI can distinguish a genuine
+ * verification pass from the "no anon key on disk" skip case. On
+ * failure the error message distinguishes three classes:
+ *   - "fetch failed" — transport error (DNS, TCP, TLS, timeout)
+ *   - "server rejected the key" — HTTP 4xx/5xx
+ *   - "server returned malformed response" — HTTP 2xx with unparseable
+ *     body
+ *
+ * The anon key is NEVER included in the returned message. Callers
+ * (the CLI entry point) render it verbatim to stderr via the errors
+ * array and exit non-zero.
+ *
+ * @internal Exported for testability.
+ */
+declare function verifyAnonKeyRegistration(projectRoot: string): Promise<VerifyAnonKeyOutcome>;
 
-export { type InitOptions, type InitResult, meetsNodeVersion, rollbackSteps, runInit };
+export { type InitOptions, type InitResult, type VerifyAnonKeyOutcome, decideMcpConfigAction, meetsNodeVersion, rollbackSteps, runInit, verifyAnonKeyRegistration };

package/dist/cli/init.d.ts

@@ -9,6 +9,14 @@ interface InitOptions {
     projectRoot: string;
     yes: boolean;
     coverageMap: boolean;
+    /**
+     * When true, skip interactive confirmation and overwrite existing
+     * MCP configuration files without prompting. Preservation of the
+     * anonymous key, config cache, and developer API key still applies
+     * regardless of this flag — `--force` only affects the MCP diff
+     * prompt (DISC-1247 Scenario 2c). Defaults to `false`.
+     */
+    force?: boolean;
 }
 /** Result of running the init command. */
 interface InitResult {
@@ -17,6 +25,30 @@ interface InitResult {
     warnings: string[];
     errors: string[];
 }
+/**
+ * Decides whether the MCP config at `configPath` should be overwritten
+ * during re-init. Returns the action to take.
+ *
+ * - `"write"` — file does not exist, or existing content already matches
+ *   the expected content. Safe to write.
+ * - `"skip"` — existing file differs AND the user chose to keep it, or
+ *   we are in a non-interactive environment without `--force`.
+ * - `"force-overwrite"` — `force === true` (or user accepted the prompt)
+ *   and content differs; overwrite.
+ *
+ * The prompt is skipped entirely when `force` is true (non-interactive
+ * overwrite) or when there is no existing file / content already matches.
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function decideMcpConfigAction(options: {
+    configPath: string | null;
+    expectedContent: string;
+    force: boolean;
+    readFile?: (p: string) => string;
+    existsSync?: (p: string) => boolean;
+    prompt?: (question: string, defaultValue: boolean) => Promise<boolean>;
+}): Promise<"write" | "skip" | "force-overwrite">;
 /**
  * Identifies a scaffolding step that can be reversed during rollback.
  * Steps are tracked in execution order and rolled back in reverse.
@@ -29,6 +61,15 @@ type CompletedStep = "instrumentation" | "next-config" | "env-local" | "gitignor
  */
 interface RollbackState {
     steps: CompletedStep[];
+    /**
+     * Absolute path of the instrumentation file that the scaffolder
+     * wrote to. May be either `{root}/instrumentation.ts` or
+     * `{root}/src/instrumentation.ts` depending on the project layout
+     * (DISC-493 Issue 1). When absent, rollback falls back to the
+     * root path for backward compatibility with callers that do not
+     * populate this field.
+     */
+    instrumentationPath?: string;
     /** Original instrumentation.ts content saved before injection.
      *  When present, rollback restores this instead of using removeRegisterGlasstrace. */
     originalInstrumentationContent?: string;
@@ -46,5 +87,49 @@ declare function rollbackSteps(steps: CompletedStep[], projectRoot: string, stat
  * bottom calls this function and translates the result to process.exit().
  */
 declare function runInit(options: InitOptions): Promise<InitResult>;
+/**
+ * Outcome of {@link verifyAnonKeyRegistration}:
+ *
+ * - `"verified"` — the server registered the anon key (HTTP 2xx with a
+ *   schema-valid response body).
+ * - `"skipped"` — no anon key was on disk, so no verification request
+ *   was sent. Typically means MCP auto-configuration failed earlier
+ *   (warnings were already emitted) — distinct from a verification
+ *   success.
+ * - `"failed"` — the verification request was sent and failed.
+ *   `error` is a user-facing message distinguishing the failure class
+ *   (`fetch failed: ...`, `server rejected the key ...`, or
+ *   `server returned malformed response ...`) with no anon key bytes.
+ */
+type VerifyAnonKeyOutcome = {
+    outcome: "verified";
+} | {
+    outcome: "skipped";
+} | {
+    outcome: "failed";
+    error: string;
+};
+/**
+ * Verifies that the anonymous key written by init is registered
+ * server-side. Called at the end of the scaffold flow so that when it
+ * fails, the user sees an actionable error rather than a misleading
+ * "initialized successfully" followed by silent MCP authentication
+ * failures (DISC-494).
+ *
+ * Returns a discriminated outcome so the CLI can distinguish a genuine
+ * verification pass from the "no anon key on disk" skip case. On
+ * failure the error message distinguishes three classes:
+ *   - "fetch failed" — transport error (DNS, TCP, TLS, timeout)
+ *   - "server rejected the key" — HTTP 4xx/5xx
+ *   - "server returned malformed response" — HTTP 2xx with unparseable
+ *     body
+ *
+ * The anon key is NEVER included in the returned message. Callers
+ * (the CLI entry point) render it verbatim to stderr via the errors
+ * array and exit non-zero.
+ *
+ * @internal Exported for testability.
+ */
+declare function verifyAnonKeyRegistration(projectRoot: string): Promise<VerifyAnonKeyOutcome>;
 
-export { type InitOptions, type InitResult, meetsNodeVersion, rollbackSteps, runInit };
+export { type InitOptions, type InitResult, type VerifyAnonKeyOutcome, decideMcpConfigAction, meetsNodeVersion, rollbackSteps, runInit, verifyAnonKeyRegistration };