@xera-ai/core 0.11.6 → 0.12.1

package/dist/src/index.js

@@ -401,7 +401,7 @@ var CoverageSchema = z4.object({
   criticalAreas: z4.array(z4.string().regex(/^[a-z0-9-]+$/)).default([]),
   autoSnapshotOnCoverage: z4.boolean().default(true)
 }).prefault({});
-var XeraConfigSchema = z4.object({
+var XeraConfigSchema = z4.strictObject({
   jira: JiraSchema,
   web: WebSchema.optional(),
   http: HttpSchema.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.11.6",
+  "version": "0.12.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@xera-ai/web": "^0.11.6",
-    "@xera-ai/http": "^0.11.6",
+    "@xera-ai/web": "^0.12.1",
+    "@xera-ai/http": "^0.12.1",
     "@playwright/test": "1.60.0",
     "dotenv": "^16.0.0",
     "fflate": "0.8.3",

package/src/bin-internal/auth-setup.ts

@@ -44,6 +44,66 @@ export async function authSetupCmd(argv: string[]): Promise<number> {
 
   let exitCode = 0;
 
+  // Pre-flight: detect requested-but-impossible shapes before we silently no-op.
+  // This is the issue #93 fix: previously `--shape http` against a project where
+  // shared/auth-setup.ts only exports `web` would print nothing and exit 0,
+  // leaving the user in an infinite "doctor says run auth-setup" loop.
+  const shapeRequestsWeb = opts.shape === 'all' || opts.shape === 'web';
+  const shapeRequestsHttp = opts.shape === 'all' || opts.shape === 'http';
+  const explicit = opts.shape !== 'all';
+
+  if (shapeRequestsWeb && config.web && typeof mod.web !== 'function') {
+    console.error(
+      `[xera:auth-setup] web adapter is configured in xera.config.ts but shared/auth-setup.ts is missing the \`web\` export.\n` +
+        `                  Add: \`export const web = defineAuthSetup(async (page, role, creds) => { ... })\` — see docs/CONFIGURATION.md`,
+    );
+    exitCode = 1;
+  }
+  if (shapeRequestsHttp && config.http && typeof mod.http !== 'function') {
+    console.error(
+      `[xera:auth-setup] http adapter is configured in xera.config.ts but shared/auth-setup.ts is missing the \`http\` export.\n` +
+        `                  Add: \`export const http = defineHttpAuthSetup(async (request, role, creds) => { ... })\` — see docs/CONFIGURATION.md`,
+    );
+    exitCode = 1;
+  }
+  if (explicit && opts.shape === 'web' && !config.web) {
+    console.error(
+      `[xera:auth-setup] --shape web requested, but xera.config.ts has no \`web\` block. Add a web: {...} block or use --shape http/all.`,
+    );
+    exitCode = 1;
+  }
+  if (explicit && opts.shape === 'http' && !config.http) {
+    console.error(
+      `[xera:auth-setup] --shape http requested, but xera.config.ts has no \`http\` block. Add an http: {...} block or use --shape web/all.`,
+    );
+    exitCode = 1;
+  }
+  if (!config.web && !config.http) {
+    console.error(
+      `[xera:auth-setup] no \`web\` or \`http\` block found in xera.config.ts — nothing to authenticate.`,
+    );
+    exitCode = 1;
+  }
+
+  // Unknown-role detection (#98): without this, a typoed --role silently
+  // matches no iteration of the per-adapter loops and we exit 0 — leaving
+  // the user wondering why `xera doctor` still reports the auth file missing.
+  if (opts.role !== undefined) {
+    const webRoles = shapeRequestsWeb && config.web ? Object.keys(config.web.auth.roles) : [];
+    const httpRoles = shapeRequestsHttp && config.http ? Object.keys(config.http.auth.roles) : [];
+    const allRoles = Array.from(new Set([...webRoles, ...httpRoles]));
+    if (allRoles.length > 0 && !allRoles.includes(opts.role)) {
+      const detail: string[] = [];
+      if (webRoles.length > 0) detail.push(`web roles: ${webRoles.join(', ')}`);
+      if (httpRoles.length > 0) detail.push(`http roles: ${httpRoles.join(', ')}`);
+      console.error(
+        `[xera:auth-setup] unknown role '${opts.role}' — configured roles: ${allRoles.join(', ')}\n` +
+          `                  (${detail.join('; ')})`,
+      );
+      return 1;
+    }
+  }
+
   // Web roles
   if (
     (opts.shape === 'all' || opts.shape === 'web') &&

package/src/bin-internal/explore-finalize.ts

@@ -0,0 +1,152 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+const CATEGORY_ENUM = z.enum([
+  'negative',
+  'boundary',
+  'state-combination',
+  'race',
+  'error-recovery',
+  'a11y',
+  'security-smell',
+  'non-functional',
+]);
+
+const ProposalsSchema = z.object({
+  proposals: z.array(
+    z.object({
+      id: z.string().min(1),
+      ticketId: z.string().min(1),
+      category: CATEGORY_ENUM,
+      severity: z.enum(['low', 'medium', 'high']),
+      title: z.string().min(1),
+      rationale: z.string().min(1),
+      gherkin: z.string().min(1),
+    }),
+  ),
+});
+
+type Proposals = z.infer<typeof ProposalsSchema>;
+type Proposal = Proposals['proposals'][number];
+
+interface ParsedArgs {
+  ticket: string;
+  accept: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  let ticket: string | undefined;
+  let accept: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--accept') {
+      const v = argv[++i];
+      if (v !== undefined) accept = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else if (a && !a.startsWith('--') && ticket === undefined) {
+      ticket = a;
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!ticket) return { error: 'ticket key is required as a positional argument' };
+  if (!accept)
+    return { error: '--accept is required (comma-separated IDs, "all", or "high-only")' };
+  return { ticket, accept };
+}
+
+function selectProposals(all: Proposal[], accept: string): Proposal[] | { error: string } {
+  const trimmed = accept.trim();
+  if (trimmed === 'all') return all;
+  if (trimmed === 'high-only') return all.filter((p) => p.severity === 'high');
+  const ids = new Set(
+    trimmed
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+  if (ids.size === 0) return { error: 'no IDs supplied' };
+  const picked = all.filter((p) => ids.has(p.id));
+  const found = new Set(picked.map((p) => p.id));
+  const missing = [...ids].filter((id) => !found.has(id));
+  if (missing.length > 0) return { error: `unknown proposal IDs: ${missing.join(', ')}` };
+  return picked;
+}
+
+function ensureFeatureHeader(ticketDir: string, ticket: string): string {
+  const explorePath = join(ticketDir, 'explore.feature');
+  if (existsSync(explorePath)) return explorePath;
+
+  // Synthesize a Feature header. Prefer copying from test.feature if present.
+  const testFeaturePath = join(ticketDir, 'test.feature');
+  let header: string;
+  if (existsSync(testFeaturePath)) {
+    const testContent = readFileSync(testFeaturePath, 'utf8');
+    const firstFeatureMatch = testContent.match(/^Feature:.*$/m);
+    header = firstFeatureMatch
+      ? `${firstFeatureMatch[0]} (adversarial)\n  Adversarial scenarios beyond the acceptance criteria.\n  Generated by /xera-explore — review before merging into test.feature.\n\n`
+      : `Feature: ${ticket} adversarial\n\n`;
+  } else {
+    header = `Feature: ${ticket} adversarial\n  Adversarial scenarios beyond the acceptance criteria.\n  Generated by /xera-explore — review before merging into test.feature.\n\n`;
+  }
+  writeFileSync(explorePath, header);
+  return explorePath;
+}
+
+function formatScenario(p: Proposal): string {
+  const tags = `@adversarial @adversarial-${p.category} @severity-${p.severity}`;
+  const rationaleComment = `  # ${p.rationale}`;
+  const indented = p.gherkin
+    .split('\n')
+    .map((line) => (line.startsWith('Scenario:') ? `  ${line}` : line ? `  ${line}` : line))
+    .join('\n');
+  return `\n  ${tags}\n${rationaleComment}\n${indented}\n`;
+}
+
+export async function exploreFinalizeCmd(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    console.error(`[explore-finalize] ${parsed.error}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const ticketDir = join(cwd, '.xera', parsed.ticket);
+  const proposalsPath = join(ticketDir, 'adversarial-proposals.json');
+  if (!existsSync(proposalsPath)) {
+    console.error(
+      `[explore-finalize] adversarial-proposals.json not found for ${parsed.ticket} — run /xera-explore Step 4 first`,
+    );
+    return 2;
+  }
+
+  let proposals: Proposals;
+  try {
+    const raw = JSON.parse(readFileSync(proposalsPath, 'utf8'));
+    proposals = ProposalsSchema.parse(raw);
+  } catch (e) {
+    console.error(`[explore-finalize] invalid proposals JSON: ${(e as Error).message}`);
+    return 1;
+  }
+
+  const picked = selectProposals(proposals.proposals, parsed.accept);
+  if ('error' in picked) {
+    console.error(`[explore-finalize] ${picked.error}`);
+    return 1;
+  }
+  if (picked.length === 0) {
+    console.error('[explore-finalize] no proposals matched the --accept filter');
+    return 1;
+  }
+
+  const explorePath = ensureFeatureHeader(ticketDir, parsed.ticket);
+  for (const p of picked) {
+    appendFileSync(explorePath, formatScenario(p));
+  }
+  console.log(
+    `[explore-finalize] appended ${picked.length} scenario(s) to ${explorePath} (${picked.map((p) => p.id).join(', ')})`,
+  );
+  return 0;
+}

package/src/bin-internal/explore-prepare.ts

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VALID_CATEGORIES = [
+  'negative',
+  'boundary',
+  'state-combination',
+  'race',
+  'error-recovery',
+  'a11y',
+  'security-smell',
+  'non-functional',
+] as const;
+
+type Category = (typeof VALID_CATEGORIES)[number];
+
+interface ParsedArgs {
+  ticket: string;
+  categoriesInclude: Category[];
+  userHint: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  let ticket: string | undefined;
+  let categoriesRaw = '';
+  let userHint = '';
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--categories') {
+      const v = argv[++i];
+      if (v !== undefined) categoriesRaw = v;
+    } else if (a === '--user-hint') {
+      const v = argv[++i];
+      if (v !== undefined) userHint = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else if (a && !a.startsWith('--') && ticket === undefined) {
+      ticket = a;
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!ticket) return { error: 'ticket key is required as a positional argument' };
+
+  const categoriesInclude: Category[] = [];
+  for (const slug of categoriesRaw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)) {
+    if (!(VALID_CATEGORIES as readonly string[]).includes(slug)) {
+      return { error: `invalid category: ${slug}` };
+    }
+    categoriesInclude.push(slug as Category);
+  }
+
+  return { ticket, categoriesInclude, userHint };
+}
+
+interface AdversarialInput {
+  ticket: { id: string; summary: string; story: string; ac: string[] };
+  existingFeature?: string;
+  existingSpec?: string;
+  adapter: 'web' | 'http';
+  categoriesInclude: Category[];
+  userHint?: string;
+}
+
+function parseStoryMd(content: string): { summary: string; ac: string[]; body: string } {
+  // story.md format: optional frontmatter with `summary:` and `ac:` (yaml-ish list),
+  // followed by the body. We do a minimal parse — full YAML is overkill here.
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) return { summary: '', ac: [], body: content };
+  const [, fm, body] = fmMatch;
+  const summaryMatch = fm!.match(/^summary:\s*(.+)$/m);
+  const summary = summaryMatch?.[1]?.trim() ?? '';
+  const ac: string[] = [];
+  const acBlock = fm!.match(/^ac:\s*\n((?:\s*-\s.+\n?)+)/m);
+  if (acBlock) {
+    for (const line of acBlock[1]!.split('\n')) {
+      const m = line.match(/^\s*-\s*(.+)$/);
+      if (m) ac.push(m[1]!.trim());
+    }
+  }
+  return { summary, ac, body: body!.trim() };
+}
+
+export async function explorePrepareCmd(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    console.error(`[explore-prepare] ${parsed.error}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const configPath = join(cwd, 'xera.config.ts');
+  if (!existsSync(configPath)) {
+    console.error('[explore-prepare] xera.config.ts not found — run inside a xera project');
+    return 2;
+  }
+
+  const ticketDir = join(cwd, '.xera', parsed.ticket);
+  const storyPath = join(ticketDir, 'story.md');
+  if (!existsSync(storyPath)) {
+    console.error(
+      `[explore-prepare] no story for ${parsed.ticket} — run /xera-fetch ${parsed.ticket} first`,
+    );
+    return 2;
+  }
+
+  const story = readFileSync(storyPath, 'utf8');
+  const { summary, ac, body } = parseStoryMd(story);
+
+  let adapter: 'web' | 'http' = 'web';
+  const metaPath = join(ticketDir, 'meta.json');
+  if (existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { adapter?: string };
+      if (meta.adapter === 'http') adapter = 'http';
+    } catch {
+      /* leave default web */
+    }
+  }
+
+  const input: AdversarialInput = {
+    ticket: { id: parsed.ticket, summary, story: body, ac },
+    adapter,
+    categoriesInclude: parsed.categoriesInclude,
+  };
+
+  const featurePath = join(ticketDir, 'test.feature');
+  if (existsSync(featurePath)) input.existingFeature = readFileSync(featurePath, 'utf8');
+
+  const specPath = join(ticketDir, 'spec.ts');
+  if (existsSync(specPath)) input.existingSpec = readFileSync(specPath, 'utf8');
+
+  if (parsed.userHint) input.userHint = parsed.userHint;
+
+  const outPath = join(ticketDir, 'adversarial-input.json');
+  writeFileSync(outPath, JSON.stringify(input, null, 2));
+  console.log(`[explore-prepare] wrote ${outPath}`);
+  return 0;
+}

package/src/bin-internal/index.ts

@@ -8,6 +8,8 @@ import { evalDeterministicCmd } from './eval-deterministic';
 import { evalPrepareCmd } from './eval-prepare';
 import { evalReportCmd } from './eval-report';
 import { execCmd } from './exec';
+import { exploreFinalizeCmd } from './explore-finalize';
+import { explorePrepareCmd } from './explore-prepare';
 import { fetchCmd } from './fetch';
 import { fillGapFinalizeCmd } from './fill-gap-finalize';
 import { fillGapPrepareCmd } from './fill-gap-prepare';
@@ -41,6 +43,8 @@ const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
   'eval-prepare': evalPrepareCmd,
   'eval-report': evalReportCmd,
   exec: execCmd,
+  'explore-finalize': exploreFinalizeCmd,
+  'explore-prepare': explorePrepareCmd,
   'fill-gap-finalize': fillGapFinalizeCmd,
   'fill-gap-prepare': fillGapPrepareCmd,
   fetch: fetchCmd,

package/src/config/schema.ts

@@ -120,7 +120,7 @@ const CoverageSchema = z
   .prefault({});
 
 export const XeraConfigSchema = z
-  .object({
+  .strictObject({
     jira: JiraSchema,
     web: WebSchema.optional(),
     http: HttpSchema.optional(),