@xera-ai/cli 0.12.0 → 0.12.2

package/dist/index.js

@@ -210,21 +210,34 @@ async function runChecks(cwd) {
     checks.push({ name: "xera skills present", ok: false, message: "run `xera init`" });
   } else {
     const required = [
-      "xera-run.md",
-      "xera-fetch.md",
-      "xera-feature.md",
-      "xera-script.md",
-      "xera-exec.md",
-      "xera-report.md",
-      "xera-promote.md"
+      "xera-run",
+      "xera-fetch",
+      "xera-feature",
+      "xera-script",
+      "xera-exec",
+      "xera-report",
+      "xera-promote"
     ];
-    const missing = required.filter((n) => !existsSync(join(skillsDir, n)));
+    const missing = [];
+    const legacyFlat = [];
+    for (const base of required) {
+      if (existsSync(join(skillsDir, base, "SKILL.md")))
+        continue;
+      if (existsSync(join(skillsDir, `${base}.md`))) {
+        legacyFlat.push(base);
+      } else {
+        missing.push(base);
+      }
+    }
     const skillsCheck = {
       name: "xera skills present",
-      ok: missing.length === 0
+      ok: missing.length === 0 && legacyFlat.length === 0
     };
-    if (missing.length)
-      skillsCheck.message = `missing: ${missing.join(", ")}`;
+    if (missing.length) {
+      skillsCheck.message = `missing: ${missing.map((b) => `${b}/SKILL.md`).join(", ")}`;
+    } else if (legacyFlat.length) {
+      skillsCheck.message = `legacy flat layout in .claude/skills/ \u2014 run \`xera init --update\` to migrate to <name>/SKILL.md (Claude Code Skill tool requires the directory layout)`;
+    }
     checks.push(skillsCheck);
   }
   return checks;
@@ -261,9 +274,16 @@ async function doctorCommand(opts) {
 }
 
 // src/commands/init.ts
-import { appendFileSync, existsSync as existsSync3, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import {
+  appendFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { createRequire } from "module";
-import { join as join3 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 import * as p from "@clack/prompts";
 import { generateKey } from "@xera-ai/core";
 import pc2 from "picocolors";
@@ -293,17 +313,6 @@ function scaffoldFile(targetPath, templateName, vars) {
   mkdirSync(dirname(targetPath), { recursive: true });
   writeFileSync(targetPath, render(tmpl, vars));
 }
-function copyDir(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src, { withFileTypes: true })) {
-    const s = join2(src, entry.name);
-    const d = join2(dest, entry.name);
-    if (entry.isDirectory())
-      copyDir(s, d);
-    else
-      writeFileSync(d, readFileSync2(s));
-  }
-}
 
 // src/commands/init.ts
 var require2 = createRequire(import.meta.url);
@@ -446,15 +455,22 @@ async function initCommand(opts) {
     writeFileSync2(gitignorePath, `${gitignoreAdditions.trim()}
 `);
   }
-  const skillsSrc = require2.resolve("@xera-ai/skills/package.json");
-  const skillsDir = join3(skillsSrc, "..");
-  for (const target of [".claude/skills", ".claude/commands"]) {
-    copyDir(skillsDir, join3(cwd, target));
-    for (const name of ["package.json", "version.json", "CHANGELOG.md"]) {
-      const f = join3(cwd, target, name);
-      if (existsSync3(f))
-        unlinkSync(f);
-    }
+  const skillsPkgPath = require2.resolve("@xera-ai/skills/package.json");
+  const skillsSrcDir = join3(skillsPkgPath, "..");
+  const SKILL_IGNORE = new Set(["package.json", "version.json", "CHANGELOG.md"]);
+  for (const name of readdirSync2(skillsSrcDir)) {
+    if (SKILL_IGNORE.has(name))
+      continue;
+    if (!name.endsWith(".md"))
+      continue;
+    const content = readFileSync3(join3(skillsSrcDir, name));
+    const base = name.replace(/\.md$/, "");
+    const skillFile = join3(cwd, ".claude/skills", base, "SKILL.md");
+    mkdirSync2(dirname2(skillFile), { recursive: true });
+    writeFileSync2(skillFile, content);
+    const cmdFile = join3(cwd, ".claude/commands", name);
+    mkdirSync2(dirname2(cmdFile), { recursive: true });
+    writeFileSync2(cmdFile, content);
   }
   const pkgPath = join3(cwd, "package.json");
   const pkg = existsSync3(pkgPath) ? JSON.parse(readFileSync3(pkgPath, "utf8")) : { name: "xera-project", private: true, type: "module" };
@@ -496,22 +512,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:
@@ -525,18 +544,97 @@ Next:
 import {
   copyFileSync,
   existsSync as existsSync4,
-  mkdirSync as mkdirSync2,
-  readdirSync as readdirSync2,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync3,
   readFileSync as readFileSync4,
+  unlinkSync,
   writeFileSync as writeFileSync3
 } from "fs";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname3, join as join4 } from "path";
 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");
@@ -566,7 +664,7 @@ async function initUpdateCommand(_opts) {
   pkg.scripts["xera:disputes"] = "xera-internal disputes";
   writeFileSync3(pkgPath, JSON.stringify(pkg, null, 2));
   const wfDir = join4(cwd, ".github/workflows");
-  mkdirSync2(wfDir, { recursive: true });
+  mkdirSync3(wfDir, { recursive: true });
   try {
     const cliPkgPath = require3.resolve("@xera-ai/cli/package.json");
     const cliTplPath = join4(cliPkgPath, "..", "templates/xera-graph.yml.template");
@@ -577,28 +675,47 @@ async function initUpdateCommand(_opts) {
   }
   const skillsSrc = require3.resolve("@xera-ai/skills/package.json");
   const newSkillsDir = join4(skillsSrc, "..");
-  const targetDirs = [join4(cwd, ".claude/skills"), join4(cwd, ".claude/commands")];
-  for (const name of readdirSync2(newSkillsDir)) {
+  const SKILL_IGNORE = new Set(["package.json", "version.json", "CHANGELOG.md"]);
+  for (const name of readdirSync3(newSkillsDir)) {
+    if (SKILL_IGNORE.has(name))
+      continue;
     if (!name.endsWith(".md"))
       continue;
     const newContent = readFileSync4(join4(newSkillsDir, name), "utf8");
-    const localStates = targetDirs.map((dir) => {
-      const path = join4(dir, name);
-      if (!existsSync4(path))
-        return { path, state: "missing" };
-      const content = readFileSync4(path, "utf8");
-      return { path, state: content === newContent ? "same" : "diff" };
-    });
-    if (localStates.every((s) => s.state === "missing")) {
-      for (const { path } of localStates) {
-        mkdirSync2(dirname2(path), { recursive: true });
+    const base = name.replace(/\.md$/, "");
+    const skillPath = join4(cwd, ".claude/skills", base, "SKILL.md");
+    const legacyFlatSkillPath = join4(cwd, ".claude/skills", name);
+    const cmdPath = join4(cwd, ".claude/commands", name);
+    let migratedLegacy = false;
+    if (existsSync4(legacyFlatSkillPath) && !existsSync4(skillPath)) {
+      const legacyContent = readFileSync4(legacyFlatSkillPath, "utf8");
+      mkdirSync3(dirname3(skillPath), { recursive: true });
+      writeFileSync3(skillPath, legacyContent);
+      unlinkSync(legacyFlatSkillPath);
+      migratedLegacy = true;
+    }
+    const targets = [];
+    for (const path of [skillPath, cmdPath]) {
+      if (!existsSync4(path)) {
+        targets.push({ path, state: "missing" });
+      } else {
+        const content = readFileSync4(path, "utf8");
+        targets.push({ path, state: content === newContent ? "same" : "diff" });
+      }
+    }
+    if (targets.every((s) => s.state === "missing")) {
+      for (const { path } of targets) {
+        mkdirSync3(dirname3(path), { recursive: true });
         writeFileSync3(path, newContent);
       }
       p2.log.info(`+ ${name}`);
       continue;
     }
-    if (localStates.every((s) => s.state === "same")) {
-      p2.log.info(`= ${name}`);
+    if (targets.every((s) => s.state === "same")) {
+      if (migratedLegacy)
+        p2.log.success(`migrated ${name} to .claude/skills/${base}/SKILL.md`);
+      else
+        p2.log.info(`= ${name}`);
       continue;
     }
     const choice = await p2.select({
@@ -609,15 +726,62 @@ async function initUpdateCommand(_opts) {
       ]
     });
     if (choice === "overwrite") {
-      for (const { path } of localStates) {
-        mkdirSync2(dirname2(path), { recursive: true });
+      for (const { path } of targets) {
+        mkdirSync3(dirname3(path), { recursive: true });
         writeFileSync3(path, newContent);
       }
       p2.log.success(`overwrote ${name}`);
     } else {
+      if (migratedLegacy)
+        p2.log.success(`migrated ${name} to .claude/skills/${base}/SKILL.md`);
       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."));
 }
 
@@ -670,7 +834,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.12.0",
+  "version": "0.12.2",
   "type": "module",
   "bin": {
     "xera": "./bin/xera"
@@ -15,8 +15,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@xera-ai/core": "^0.12.0",
-    "@xera-ai/skills": "^0.12.0",
+    "@xera-ai/core": "^0.12.2",
+    "@xera-ai/skills": "^0.12.2",
     "@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}}',