@xera-ai/cli 0.11.6 → 0.12.1

package/dist/index.js

@@ -480,6 +480,8 @@ async function initCommand(opts) {
   pkg.scripts["xera:impact-prepare"] = "xera-internal impact-prepare";
   pkg.scripts["xera:heal-prepare"] = "xera-internal heal-prepare";
   pkg.scripts["xera:disputes"] = "xera-internal disputes";
+  pkg.scripts["xera:explore-prepare"] = "xera-internal explore-prepare";
+  pkg.scripts["xera:explore-finalize"] = "xera-internal explore-finalize";
   pkg.dependencies = pkg.dependencies ?? {};
   pkg.dependencies["@xera-ai/core"] = `^${CLI_VERSION}`;
   pkg.dependencies["@xera-ai/prompts"] = `^${CLI_VERSION}`;
@@ -494,22 +496,25 @@ async function initCommand(opts) {
   writeFileSync2(pkgPath, JSON.stringify(pkg, null, 2));
   const nextSteps = shape === "api" ? `
 Next:
-  1) Set your auth credentials in .env.local:
-       USER_BEARER_TOKEN=...
+  1) Copy .env.example to .env and set your auth credentials:
+       cp .env.example .env
+       # then edit .env to set USER_BEARER_TOKEN=...
   2) Run pre-authentication:
        bun run xera:auth-setup
   3) Start testing:
        Open Claude Code in this directory and run: /xera-run <TICKET>
 ` : shape === "mixed" ? `
 Next:
-  1) Set credentials in .env.local (both web logins and API tokens)
+  1) Copy .env.example to .env and set credentials (both web logins and API tokens):
+       cp .env.example .env
   2) Run pre-authentication:
        bun run xera:auth-setup
   3) Start testing:
        Open Claude Code in this directory and run: /xera-run <TICKET>
 ` : `
 Next:
-  1) Set your Jira credentials in .env.local
+  1) Copy .env.example to .env and set your Jira credentials:
+       cp .env.example .env
   2) Run pre-authentication:
        bun run xera:auth-setup
   3) Start testing:
@@ -534,7 +539,85 @@ import * as p2 from "@clack/prompts";
 import pc3 from "picocolors";
 var require3 = createRequire2(import.meta.url);
 var CLI_VERSION2 = require3("../package.json").version;
-async function initUpdateCommand(_opts) {
+function detectAdaptersFromConfig(cwd) {
+  const configPath = join4(cwd, "xera.config.ts");
+  if (!existsSync4(configPath))
+    return null;
+  const cfg = readFileSync4(configPath, "utf8");
+  const m = cfg.match(/adapters:\s*\[([^\]]+)\]/);
+  if (!m)
+    return null;
+  return (m[1].match(/'(\w+)'/g) ?? []).map((s) => s.slice(1, -1));
+}
+function adaptersForShape(shape) {
+  if (shape === "web")
+    return ["web"];
+  if (shape === "api")
+    return ["http"];
+  return ["web", "http"];
+}
+function renderHttpConfigSnippet(opts) {
+  const baseUrl = opts.apiBaseUrl ?? "https://api.staging.example.com";
+  const strategy = opts.authStrategy ?? "bearer";
+  const roles = (opts.httpRoles ?? "user").split(",").map((s) => s.trim()).filter(Boolean);
+  const rolesBlock = roles.map((r) => `        ${r}: { tokenEnv: '${r.toUpperCase().replace(/-/g, "_")}_BEARER_TOKEN' },`).join(`
+`);
+  const specLine = opts.openapiPath ? `    spec: '${opts.openapiPath}',
+` : "";
+  return [
+    `  http: {`,
+    `    baseUrl: { staging: '${baseUrl}' },`,
+    `    defaultEnv: 'staging',`,
+    `${specLine}    auth: {`,
+    `      strategy: '${strategy}',`,
+    `      roles: {`,
+    rolesBlock,
+    `      },`,
+    `    },`,
+    `  },`
+  ].join(`
+`);
+}
+function renderWebConfigSnippet(opts) {
+  const baseUrl = opts.stagingUrl ?? "https://staging.example.com";
+  const roles = (opts.roles ?? "admin,regular").split(",").map((s) => s.trim()).filter(Boolean);
+  const authBlock = opts.authEnabled === false ? "" : `    auth: {
+      strategy: 'storageState',
+      setupScript: './shared/auth-setup.ts',
+      roles: {
+${roles.map((r) => `        ${r}: { envEmail: 'TEST_${r.toUpperCase().replace(/-/g, "_")}_EMAIL', envPassword: 'TEST_${r.toUpperCase().replace(/-/g, "_")}_PWD' },`).join(`
+`)}
+      },
+    },
+`;
+  return [
+    `  web: {`,
+    `    baseUrl: { staging: '${baseUrl}' },`,
+    `    defaultEnv: 'staging',`,
+    authBlock + `  },`
+  ].join(`
+`);
+}
+var HTTP_AUTH_SETUP_SNIPPET = `import { defineHttpAuthSetup, presetHttpAuth } from '@xera-ai/http';
+
+export const http = defineHttpAuthSetup(async (request, role, creds) => {
+  return presetHttpAuth({
+    request,
+    role,
+    config: (globalThis as Record<string, unknown>).__XERA_HTTP_CONFIG__ as never,
+  });
+});`;
+var WEB_AUTH_SETUP_SNIPPET = `import { defineAuthSetup } from '@xera-ai/web';
+
+export const web = defineAuthSetup(async (page, _role, creds) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(creds.email);
+  await page.getByLabel('Password').fill(creds.password);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await page.waitForURL(/.*\\/dashboard/);
+  return { expiresAt: Date.now() + 8 * 3600 * 1000 };
+});`;
+async function initUpdateCommand(opts) {
   const cwd = process.cwd();
   p2.intro(pc3.cyan("xera init --update"));
   const pkgPath = join4(cwd, "package.json");
@@ -616,6 +699,51 @@ async function initUpdateCommand(_opts) {
       p2.log.warn(`kept local ${name}`);
     }
   }
+  const hasShapeFlags = opts.apiBaseUrl !== undefined || opts.openapiPath !== undefined || opts.authStrategy !== undefined || opts.httpRoles !== undefined || opts.stagingUrl !== undefined || opts.authEnabled !== undefined || opts.roles !== undefined;
+  if (opts.shape !== undefined) {
+    const current = detectAdaptersFromConfig(cwd);
+    if (current === null) {
+      p2.log.warn("--shape was provided but could not detect existing adapters in xera.config.ts. Skipping shape check.");
+    } else {
+      const requested = adaptersForShape(opts.shape);
+      const missing = requested.filter((a) => !current.includes(a));
+      const extra = current.filter((a) => !requested.includes(a));
+      if (missing.length === 0 && extra.length === 0) {
+        p2.log.info(`shape '${opts.shape}' already matches existing adapters [${current.join(", ")}]`);
+      } else {
+        if (missing.length > 0) {
+          const lines = [
+            `--shape ${opts.shape} requested but xera.config.ts has adapters: [${current.join(", ")}]`,
+            `Missing adapter(s): ${missing.join(", ")}`,
+            ``,
+            `init --update is non-destructive \u2014 it will NOT modify xera.config.ts or shared/auth-setup.ts.`,
+            `To complete the upgrade, hand-edit both files:`,
+            ``,
+            `1. In xera.config.ts, change \`adapters: [${current.map((a) => `'${a}'`).join(", ")}]\` to \`adapters: [${requested.map((a) => `'${a}'`).join(", ")}]\` and add this block inside defineConfig({...}):`,
+            ``
+          ];
+          for (const a of missing) {
+            lines.push(a === "http" ? renderHttpConfigSnippet(opts) : renderWebConfigSnippet(opts));
+            lines.push("");
+          }
+          lines.push(`2. In shared/auth-setup.ts, add this export:`);
+          lines.push("");
+          for (const a of missing) {
+            lines.push(a === "http" ? HTTP_AUTH_SETUP_SNIPPET : WEB_AUTH_SETUP_SNIPPET);
+            lines.push("");
+          }
+          lines.push(`3. Add ${missing.includes("http") ? `\`@xera-ai/http\`` : ""}${missing.includes("http") && missing.includes("web") ? " and " : ""}${missing.includes("web") ? `\`@xera-ai/web\`` : ""} to dependencies (re-run \`xera init --update\` after editing to bump versions), then run \`xera doctor\` to verify.`);
+          p2.log.warn(lines.join(`
+`));
+        }
+        if (extra.length > 0) {
+          p2.log.warn(`--shape ${opts.shape} would remove adapter(s) [${extra.join(", ")}] from xera.config.ts, but init --update never removes config. Remove the block(s) by hand if intended.`);
+        }
+      }
+    }
+  } else if (hasShapeFlags) {
+    p2.log.warn("Shape-related flags (--au/--as/--hr/--su/--ro/--op/--auth-enabled) are ignored by init --update without --shape. To change shape, pass --shape <web|api|mixed> alongside.");
+  }
   p2.outro(pc3.green("Update complete. Run `xera doctor` to verify."));
 }
 
@@ -668,7 +796,38 @@ async function main() {
   cli.usage("<command> [options]");
   cli.command("init", "Scaffold a new xera project in the current directory").option("--update", "Non-destructive refresh of an existing project").option("-y, --yes", "Accept all defaults (non-interactive)").option("--shape <shape>", "Project shape: web | api | mixed").option("--ju, --jira-base-url <url>", "Jira workspace URL").option("--pk, --project-keys <keys>", "Jira project key(s), comma-separated").option("--sf, --story-field <field>", "Jira field id for user story (default: description)").option("--ac, --ac-field <field>", "Jira field id for acceptance criteria").option("--su, --staging-url <url>", "Web app staging URL").option("--auth-enabled", "App requires login to test most pages").option("--no-auth-enabled", "App does not require login").option("--ro, --roles <roles>", "Test user roles, comma-separated (default: admin,regular)").option("--au, --api-base-url <url>", "API base URL").option("--op, --openapi-path <path>", "OpenAPI spec path or URL").option("--as, --auth-strategy <strategy>", `API auth strategy: ${VALID_AUTH_STRATEGIES.join(" | ")}`).option("--hr, --http-roles <roles>", "HTTP test roles, comma-separated (default: user)").example("xera init").example("xera init -y --shape web").example("xera init -y --shape api --pk MYPROJ --ju https://myco.atlassian.net --au https://api.staging.example.com --as bearer").example("xera init -y --shape mixed --pk PROJ --ju https://myco.atlassian.net --su https://staging.example.com --au https://api.staging.example.com").action(async (opts) => {
     if (opts.update) {
-      await initUpdateCommand({ yes: !!opts.yes });
+      const updateOpts = { yes: !!opts.yes };
+      if (opts.shape !== undefined) {
+        if (!VALID_SHAPES.includes(opts.shape)) {
+          console.error(pc4.red(`
+  error: --shape must be one of: ${VALID_SHAPES.join(", ")}
+`));
+          process.exit(1);
+        }
+        updateOpts.shape = opts.shape;
+      }
+      if (opts.authStrategy !== undefined) {
+        if (!VALID_AUTH_STRATEGIES.includes(opts.authStrategy)) {
+          console.error(pc4.red(`
+  error: --auth-strategy must be one of: ${VALID_AUTH_STRATEGIES.join(", ")}
+`));
+          process.exit(1);
+        }
+        updateOpts.authStrategy = opts.authStrategy;
+      }
+      if (opts.apiBaseUrl !== undefined)
+        updateOpts.apiBaseUrl = opts.apiBaseUrl;
+      if (opts.openapiPath !== undefined)
+        updateOpts.openapiPath = opts.openapiPath;
+      if (opts.httpRoles !== undefined)
+        updateOpts.httpRoles = opts.httpRoles;
+      if (opts.stagingUrl !== undefined)
+        updateOpts.stagingUrl = opts.stagingUrl;
+      if (opts.authEnabled !== undefined)
+        updateOpts.authEnabled = opts.authEnabled;
+      if (opts.roles !== undefined)
+        updateOpts.roles = opts.roles;
+      await initUpdateCommand(updateOpts);
       return;
     }
     const initOpts = { yes: !!opts.yes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/cli",
-  "version": "0.11.6",
+  "version": "0.12.1",
   "type": "module",
   "bin": {
     "xera": "./bin/xera"
@@ -15,8 +15,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@xera-ai/core": "^0.11.6",
-    "@xera-ai/skills": "^0.11.6",
+    "@xera-ai/core": "^0.12.1",
+    "@xera-ai/skills": "^0.12.1",
     "@clack/prompts": "1.4.0",
     "cac": "7.0.0",
     "picocolors": "1.1.1"

package/templates/http-env.example.tmpl

@@ -2,6 +2,6 @@
 JIRA_EMAIL=
 JIRA_API_TOKEN=
 
-# Auth tokens for HTTP roles - set in .env.local (gitignored)
+# Auth tokens for HTTP roles - set in .env (gitignored)
 {{#each httpRoles}}{{upper this}}_BEARER_TOKEN=
 {{/each}}

package/templates/http-xera.config.ts.tmpl

@@ -11,8 +11,8 @@ export default defineConfig({
     },
   },
   http: {
-    baseUrl: { dev: '{{apiBaseUrl}}' },
-    defaultEnv: 'dev',
+    baseUrl: { staging: '{{apiBaseUrl}}' },
+    defaultEnv: 'staging',
     {{#if openapiPath}}spec: '{{openapiPath}}',{{/if}}
     auth: {
       strategy: '{{authStrategy}}',

package/templates/mixed-xera.config.ts.tmpl

@@ -11,8 +11,8 @@ export default defineConfig({
     },
   },
   web: {
-    baseUrl: { dev: '{{stagingUrl}}' },
-    defaultEnv: 'dev',
+    baseUrl: { staging: '{{stagingUrl}}' },
+    defaultEnv: 'staging',
     {{#if authEnabled}}auth: {
       strategy: 'storageState',
       setupScript: './shared/auth-setup.ts',
@@ -23,8 +23,8 @@ export default defineConfig({
     },{{/if}}
   },
   http: {
-    baseUrl: { dev: '{{apiBaseUrl}}' },
-    defaultEnv: 'dev',
+    baseUrl: { staging: '{{apiBaseUrl}}' },
+    defaultEnv: 'staging',
     {{#if openapiPath}}spec: '{{openapiPath}}',{{/if}}
     auth: {
       strategy: '{{authStrategy}}',