@xera-ai/core 0.1.0

package/dist/lock/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/lock/file-lock.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAgBhE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGtD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAcjD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9C"}

package/dist/logging/ndjson-logger.d.ts

@@ -0,0 +1,11 @@
+export interface LogEntry {
+    ts: string;
+    [key: string]: unknown;
+}
+export declare class NdjsonLogger {
+    private readonly path;
+    constructor(path: string);
+    log(payload: Record<string, unknown>): void;
+    static readAll(path: string): LogEntry[];
+}
+//# sourceMappingURL=ndjson-logger.d.ts.map

package/dist/logging/ndjson-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ndjson-logger.d.ts","sourceRoot":"","sources":["../../src/logging/ndjson-logger.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAIzC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAK3C,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE;CAMzC"}

package/dist/reporter/jira-comment.d.ts

@@ -0,0 +1,9 @@
+import type { ClassifyOutput } from '../classifier/types';
+export interface JiraCommentInput extends ClassifyOutput {
+    ticket: string;
+    runId: string;
+    xeraVersion: string;
+    promptsVersion: string;
+}
+export declare function buildJiraComment(input: JiraCommentInput): string;
+//# sourceMappingURL=jira-comment.d.ts.map

package/dist/reporter/jira-comment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jira-comment.d.ts","sourceRoot":"","sources":["../../src/reporter/jira-comment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAqBhE"}

package/dist/reporter/status-writer.d.ts

@@ -0,0 +1,14 @@
+import type { ClassifyOutput } from '../classifier/types';
+export interface StatusWriterInput {
+    ticket: string;
+    runTs: string;
+    classification: ClassifyOutput;
+    scenarioCounts: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+    };
+}
+export declare function writeStatusFromClassification(path: string, input: StatusWriterInput): void;
+//# sourceMappingURL=status-writer.d.ts.map

package/dist/reporter/status-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-writer.d.ts","sourceRoot":"","sources":["../../src/reporter/status-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,cAAc,CAAC;IAC/B,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACpF;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAyB1F"}

package/dist/src/index.js

@@ -0,0 +1,587 @@
+// @bun
+// src/config/schema.ts
+import { z } from "zod";
+var AuthRoleSchema = z.object({
+  envEmail: z.string().min(1),
+  envPassword: z.string().min(1)
+});
+var AuthSchema = z.object({
+  strategy: z.enum(["storageState", "apiToken", "none"]).default("none"),
+  ttl: z.string().default("8h"),
+  refreshBuffer: z.string().default("30m"),
+  setupScript: z.string().optional(),
+  roles: z.record(z.string(), AuthRoleSchema).default({})
+});
+var WebSchema = z.object({
+  baseUrl: z.record(z.string(), z.string().url()).refine((m) => Object.keys(m).length > 0, {
+    message: "baseUrl must have at least one environment"
+  }),
+  defaultEnv: z.string(),
+  auth: AuthSchema.default({}),
+  testData: z.object({
+    users: z.record(z.string(), z.object({ fromAuth: z.string() })).default({})
+  }).default({ users: {} })
+}).refine((w) => w.baseUrl[w.defaultEnv] !== undefined, {
+  message: "defaultEnv must exist in baseUrl map",
+  path: ["defaultEnv"]
+});
+var JiraSchema = z.object({
+  baseUrl: z.string().url(),
+  projectKeys: z.array(z.string().min(1)).min(1),
+  fields: z.object({
+    story: z.string().min(1),
+    acceptanceCriteria: z.string().optional(),
+    attachments: z.string().default("attachment")
+  })
+});
+var AISchema = z.object({
+  livePageSnapshot: z.boolean().default(true),
+  confidenceThreshold: z.enum(["low", "medium", "high"]).default("medium"),
+  maxRetries: z.object({
+    typecheck: z.number().int().min(0).max(5).default(2),
+    lint: z.number().int().min(0).max(5).default(2),
+    validateFeature: z.number().int().min(0).max(5).default(2)
+  }).default({})
+}).default({});
+var ReportingSchema = z.object({
+  language: z.enum(["en", "vi"]).default("en"),
+  postToJira: z.boolean().default(true),
+  transition: z.object({
+    onPass: z.string().nullable().default(null),
+    onFail: z.string().nullable().default(null)
+  }).default({}),
+  artifactLinks: z.enum(["git", "local"]).default("git")
+}).default({});
+var XeraConfigSchema = z.object({
+  jira: JiraSchema,
+  web: WebSchema,
+  ai: AISchema,
+  reporting: ReportingSchema,
+  adapters: z.array(z.string().min(1)).min(1).default(["web"])
+});
+// src/config/define.ts
+function defineConfig(config) {
+  return config;
+}
+// src/config/load.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+async function loadConfig(cwd) {
+  const path = join(cwd, "xera.config.ts");
+  if (!existsSync(path)) {
+    throw new Error(`xera.config.ts not found in ${cwd}`);
+  }
+  const mod = await import(pathToFileURL(path).href);
+  const raw = mod.default ?? mod;
+  return XeraConfigSchema.parse(raw);
+}
+// src/artifact/paths.ts
+import { join as join2 } from "path";
+var TICKET_RE = /^[A-Z][A-Z0-9_]*-\d+$|^SAMPLE-\d+$/;
+function resolveArtifactPaths(repoRoot, ticket) {
+  if (!TICKET_RE.test(ticket)) {
+    throw new Error(`Invalid ticket key: "${ticket}" (expected e.g. JIRA-123 or SAMPLE-001)`);
+  }
+  const ticketDir = join2(repoRoot, ".xera", ticket);
+  return {
+    ticketDir,
+    storyPath: join2(ticketDir, "story.md"),
+    featurePath: join2(ticketDir, "test.feature"),
+    specPath: join2(ticketDir, "spec.ts"),
+    pageObjectsDir: join2(ticketDir, "page-objects"),
+    runsDir: join2(ticketDir, "runs"),
+    metaPath: join2(ticketDir, "meta.json"),
+    statusPath: join2(ticketDir, "status.json"),
+    logPath: join2(ticketDir, "xera.log"),
+    lockPath: join2(ticketDir, ".lock"),
+    authDir: join2(repoRoot, ".xera", ".auth"),
+    runPath: (runId) => {
+      const runDir = join2(ticketDir, "runs", runId);
+      return {
+        runDir,
+        reportJsonPath: join2(runDir, "report.json"),
+        tracePath: join2(runDir, "trace.zip"),
+        normalizedPath: join2(runDir, "normalized.json"),
+        screenshotsDir: join2(runDir, "screenshots"),
+        videoDir: join2(runDir, "videos")
+      };
+    }
+  };
+}
+function generateRunId(now = new Date) {
+  return now.toISOString().replace(/[:.]/g, "-").replace("Z", "");
+}
+// src/artifact/hash.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, readFileSync } from "fs";
+function hashString(s) {
+  return `sha256:${createHash("sha256").update(s).digest("hex")}`;
+}
+function hashFile(path) {
+  return hashString(readFileSync(path, "utf8"));
+}
+function hashFileIfExists(path) {
+  if (!existsSync2(path))
+    return null;
+  return hashFile(path);
+}
+// src/artifact/meta.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { z as z2 } from "zod";
+var MetaJsonSchema = z2.object({
+  ticket: z2.string(),
+  adapter: z2.string(),
+  xera_version: z2.string(),
+  prompts_version: z2.string(),
+  fetched_at: z2.string().optional(),
+  story_hash: z2.string().optional(),
+  feature_generated_at: z2.string().optional(),
+  feature_generated_from_story_hash: z2.string().optional(),
+  feature_hash: z2.string().optional(),
+  script_generated_at: z2.string().optional(),
+  script_generated_from_feature_hash: z2.string().optional(),
+  script_warnings: z2.array(z2.string()).optional()
+});
+function readMeta(path) {
+  if (!existsSync3(path))
+    return null;
+  return MetaJsonSchema.parse(JSON.parse(readFileSync2(path, "utf8")));
+}
+function writeMeta(path, meta) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(meta, null, 2));
+}
+function updateMeta(path, patch) {
+  const existing = readMeta(path);
+  if (!existing) {
+    throw new Error(`meta.json not found at ${path}; cannot update`);
+  }
+  const next = { ...existing, ...patch };
+  writeMeta(path, next);
+  return next;
+}
+// src/artifact/status.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+import { z as z3 } from "zod";
+var ClassificationEnum = z3.enum(["PASS", "REAL_BUG", "SELECTOR_DRIFT", "FLAKY", "TEST_BUG"]);
+var ResultEnum = z3.enum(["PASS", "FAIL"]);
+var ConfidenceEnum = z3.enum(["low", "medium", "high"]);
+var HistoryEntrySchema = z3.object({
+  ts: z3.string(),
+  result: ResultEnum,
+  class: ClassificationEnum
+});
+var StatusJsonSchema = z3.object({
+  ticket: z3.string(),
+  lastRun: z3.string(),
+  result: ResultEnum,
+  classification: ClassificationEnum,
+  confidence: ConfidenceEnum,
+  scenarios: z3.object({
+    total: z3.number().int().nonnegative(),
+    passed: z3.number().int().nonnegative(),
+    failed: z3.number().int().nonnegative(),
+    skipped: z3.number().int().nonnegative()
+  }),
+  history: z3.array(HistoryEntrySchema).default([]),
+  last_jira_comment_id: z3.string().optional()
+});
+var HISTORY_CAP = 20;
+function readStatus(path) {
+  if (!existsSync4(path))
+    return null;
+  return StatusJsonSchema.parse(JSON.parse(readFileSync3(path, "utf8")));
+}
+function writeStatus(path, status) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, JSON.stringify(status, null, 2));
+}
+function appendHistory(path, entry) {
+  const s = readStatus(path);
+  if (!s) {
+    throw new Error(`status.json not found at ${path}`);
+  }
+  s.history = [entry, ...s.history].slice(0, HISTORY_CAP);
+  writeStatus(path, s);
+  return s;
+}
+// src/logging/ndjson-logger.ts
+import { appendFileSync, mkdirSync as mkdirSync3, existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname3 } from "path";
+
+class NdjsonLogger {
+  path;
+  constructor(path) {
+    this.path = path;
+    mkdirSync3(dirname3(path), { recursive: true });
+  }
+  log(payload) {
+    const entry = { ts: new Date().toISOString(), ...payload };
+    appendFileSync(this.path, `${JSON.stringify(entry)}
+`);
+  }
+  static readAll(path) {
+    if (!existsSync5(path))
+      return [];
+    const txt = readFileSync4(path, "utf8").trim();
+    if (!txt)
+      return [];
+    return txt.split(`
+`).map((line) => JSON.parse(line));
+  }
+}
+// src/lock/file-lock.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync3, unlinkSync, mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname4 } from "path";
+import { hostname } from "os";
+function acquireLock(path, runId) {
+  if (existsSync6(path))
+    return false;
+  mkdirSync4(dirname4(path), { recursive: true });
+  const data = {
+    pid: process.pid,
+    hostname: hostname(),
+    started_at: new Date().toISOString(),
+    run_id: runId
+  };
+  try {
+    writeFileSync3(path, JSON.stringify(data), { flag: "wx" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function releaseLock(path) {
+  if (existsSync6(path))
+    unlinkSync(path);
+}
+function readLock(path) {
+  if (!existsSync6(path))
+    return null;
+  return JSON.parse(readFileSync5(path, "utf8"));
+}
+function isLockStale(path) {
+  const lock = readLock(path);
+  if (!lock)
+    return true;
+  if (lock.hostname !== hostname()) {
+    return false;
+  }
+  try {
+    process.kill(lock.pid, 0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+function forceUnlock(path) {
+  releaseLock(path);
+}
+// src/jira/mcp-backend.ts
+import { existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync4, mkdirSync as mkdirSync5 } from "fs";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+var MCP_ENV = "XERA_MCP_JIRA";
+async function createMcpBackend(_baseUrl) {
+  if (process.env[MCP_ENV] !== "1")
+    return null;
+  const tmpDir = join3(tmpdir(), "xera-mcp");
+  mkdirSync5(tmpDir, { recursive: true });
+  return {
+    backend: "mcp",
+    async fetchTicket(key, _fields) {
+      const cachePath = join3(tmpDir, `${key}.json`);
+      if (!existsSync7(cachePath)) {
+        throw new Error(`MCP-mode fetch requires the skill to first call mcp__atlassian__getJiraIssue and write ${cachePath}. ` + `If you are running this directly, unset ${MCP_ENV} to use REST.`);
+      }
+      const parsed = JSON.parse(readFileSync6(cachePath, "utf8"));
+      return parsed;
+    },
+    async postComment(key, body) {
+      const outPath = join3(tmpDir, `${key}.comment.json`);
+      writeFileSync4(outPath, JSON.stringify({ key, body }));
+      return { id: "mcp-pending" };
+    },
+    async transitionStatus(key, statusName) {
+      const outPath = join3(tmpDir, `${key}.transition.json`);
+      writeFileSync4(outPath, JSON.stringify({ key, statusName }));
+    },
+    async listFields(_sampleKey) {
+      throw new Error("listFields is REST-only; init flow uses REST for field discovery.");
+    }
+  };
+}
+
+// src/jira/rest-backend.ts
+function createRestBackend(baseUrl, creds) {
+  const authHeader = `Basic ${Buffer.from(`${creds.email}:${creds.apiToken}`).toString("base64")}`;
+  const base = baseUrl.replace(/\/$/, "");
+  async function req(path, init) {
+    const r = await fetch(`${base}${path}`, {
+      ...init,
+      headers: {
+        Authorization: authHeader,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...init?.headers ?? {}
+      }
+    });
+    if (!r.ok && r.status !== 201) {
+      throw new Error(`Jira REST ${init?.method ?? "GET"} ${path} failed: ${r.status} ${await r.text()}`);
+    }
+    return r;
+  }
+  return {
+    backend: "rest",
+    async fetchTicket(key, fields) {
+      const want = ["summary", fields.story];
+      if (fields.acceptanceCriteria)
+        want.push(fields.acceptanceCriteria);
+      want.push("attachment");
+      const r = await req(`/rest/api/3/issue/${encodeURIComponent(key)}?fields=${want.join(",")}`);
+      const json = await r.json();
+      const f = json.fields;
+      const attachments = Array.isArray(f.attachment) ? f.attachment.map((a) => ({ filename: a.filename, url: a.content })) : [];
+      const ticket = {
+        key: json.key,
+        summary: String(f.summary ?? ""),
+        story: String(f[fields.story] ?? ""),
+        attachments,
+        raw: f
+      };
+      if (fields.acceptanceCriteria) {
+        ticket.acceptanceCriteria = String(f[fields.acceptanceCriteria] ?? "");
+      }
+      return ticket;
+    },
+    async postComment(key, body) {
+      const r = await req(`/rest/api/3/issue/${encodeURIComponent(key)}/comment`, {
+        method: "POST",
+        body: JSON.stringify({
+          body: { type: "doc", version: 1, content: [{ type: "paragraph", content: [{ type: "text", text: body }] }] }
+        })
+      });
+      const json = await r.json();
+      return { id: json.id };
+    },
+    async transitionStatus(key, statusName) {
+      const tr = await req(`/rest/api/3/issue/${encodeURIComponent(key)}/transitions`);
+      const json = await tr.json();
+      const t = json.transitions.find((x) => x.name === statusName);
+      if (!t)
+        throw new Error(`No transition named "${statusName}" available for ${key}`);
+      await req(`/rest/api/3/issue/${encodeURIComponent(key)}/transitions`, {
+        method: "POST",
+        body: JSON.stringify({ transition: { id: t.id } })
+      });
+    },
+    async listFields(sampleKey) {
+      const r = await req(`/rest/api/3/issue/${encodeURIComponent(sampleKey)}?fields=*all`);
+      const json = await r.json();
+      return Object.entries(json.fields).map(([id, value]) => ({
+        id,
+        name: id,
+        hasContent: value !== null && value !== undefined && value !== ""
+      }));
+    }
+  };
+}
+
+// src/jira/client.ts
+async function createJiraClient(opts) {
+  if (opts.preferMcp !== false) {
+    const mcp = await createMcpBackend(opts.baseUrl);
+    if (mcp)
+      return mcp;
+  }
+  if (!opts.rest) {
+    throw new Error("Atlassian MCP not connected and no REST credentials provided (JIRA_EMAIL + JIRA_API_TOKEN).");
+  }
+  return createRestBackend(opts.baseUrl, opts.rest);
+}
+// src/jira/fields.ts
+var PREFERRED_STORY_IDS = ["description", "story"];
+function rankStoryCandidates(fields) {
+  return fields.filter((f) => f.hasContent).filter((f) => !["attachment", "comment", "created", "updated", "reporter", "creator"].includes(f.id)).sort((a, b) => {
+    const ai = PREFERRED_STORY_IDS.indexOf(a.id);
+    const bi = PREFERRED_STORY_IDS.indexOf(b.id);
+    if (ai >= 0 && bi >= 0)
+      return ai - bi;
+    if (ai >= 0)
+      return -1;
+    if (bi >= 0)
+      return 1;
+    return a.id.localeCompare(b.id);
+  });
+}
+// src/jira/retry.ts
+async function withRetry(fn, opts) {
+  let attempt = 0;
+  let lastErr;
+  while (attempt < opts.maxAttempts) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (opts.shouldRetry && !opts.shouldRetry(err))
+        throw err;
+      attempt++;
+      if (attempt >= opts.maxAttempts)
+        break;
+      const delay = opts.baseMs * Math.pow(opts.factor, attempt - 1);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+  throw lastErr;
+}
+// src/auth/encrypt.ts
+import { randomBytes, createCipheriv, createDecipheriv } from "crypto";
+var ALGO = "aes-256-gcm";
+var KEY_LEN = 32;
+var IV_LEN = 12;
+var TAG_LEN = 16;
+var VERSION = "v1";
+function generateKey() {
+  return randomBytes(KEY_LEN).toString("hex");
+}
+function keyToBuf(key) {
+  const buf = Buffer.from(key, "hex");
+  if (buf.length !== KEY_LEN)
+    throw new Error(`Key must be ${KEY_LEN} bytes (got ${buf.length})`);
+  return buf;
+}
+function encrypt(plaintext, keyHex) {
+  const key = keyToBuf(keyHex);
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${VERSION}:${iv.toString("base64")}:${tag.toString("base64")}:${ct.toString("base64")}`;
+}
+function decrypt(ciphertext, keyHex) {
+  const [version, ivB64, tagB64, ctB64] = ciphertext.split(":");
+  if (version !== VERSION)
+    throw new Error(`Unsupported ciphertext version: ${version}`);
+  if (!ivB64 || !tagB64 || !ctB64)
+    throw new Error("Malformed ciphertext");
+  const key = keyToBuf(keyHex);
+  const iv = Buffer.from(ivB64, "base64");
+  const tag = Buffer.from(tagB64, "base64");
+  const ct = Buffer.from(ctB64, "base64");
+  if (tag.length !== TAG_LEN)
+    throw new Error("Bad auth tag length");
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+}
+// src/auth/key.ts
+var AUTH_KEY_ENV = "XERA_AUTH_KEY";
+function resolveAuthKey() {
+  const key = process.env[AUTH_KEY_ENV];
+  if (!key) {
+    throw new Error(`${AUTH_KEY_ENV} not set. It is auto-generated by \`xera init\` and saved to .env. ` + `If you deleted .env, regenerate it by running \`xera init --update\` \u2014 note that any cached auth state will be invalidated.`);
+  }
+  if (!/^[0-9a-f]{64}$/i.test(key)) {
+    throw new Error(`${AUTH_KEY_ENV} must be a 64-character hex string (32 bytes).`);
+  }
+  return key;
+}
+// src/auth/state.ts
+import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync5, mkdirSync as mkdirSync6 } from "fs";
+import { join as join4 } from "path";
+import { z as z4 } from "zod";
+var AuthStateEntrySchema = z4.object({
+  role: z4.string(),
+  strategy: z4.enum(["storageState", "apiToken"]),
+  created_at: z4.string(),
+  expires_at: z4.string(),
+  payload: z4.record(z4.string(), z4.unknown())
+});
+function pathFor(authDir, role) {
+  return join4(authDir, `${role}.json`);
+}
+function writeAuthState(authDir, entry) {
+  mkdirSync6(authDir, { recursive: true });
+  const ct = encrypt(JSON.stringify(entry), resolveAuthKey());
+  writeFileSync5(pathFor(authDir, entry.role), ct);
+}
+function readAuthState(authDir, role) {
+  const p = pathFor(authDir, role);
+  if (!existsSync8(p))
+    return null;
+  const txt = readFileSync7(p, "utf8");
+  const plain = decrypt(txt, resolveAuthKey());
+  return AuthStateEntrySchema.parse(JSON.parse(plain));
+}
+// src/auth/refresh.ts
+var RE = /^(\d+)([hms])$/;
+function parseDuration(d) {
+  const m = RE.exec(d);
+  if (!m)
+    throw new Error(`Bad duration "${d}" \u2014 expected e.g. "8h", "30m", "45s"`);
+  const n = Number(m[1]);
+  const unit = m[2];
+  if (unit === "h")
+    return n * 3600 * 1000;
+  if (unit === "m")
+    return n * 60 * 1000;
+  return n * 1000;
+}
+function needsRefresh(entry, policy, now = new Date) {
+  if (!entry)
+    return true;
+  const ttlMs = parseDuration(policy.ttl);
+  const bufMs = parseDuration(policy.refreshBuffer);
+  const createdAt = new Date(entry.created_at).getTime();
+  if (now.getTime() - createdAt > ttlMs)
+    return true;
+  const expiresAt = new Date(entry.expires_at).getTime();
+  if (expiresAt - now.getTime() < bufMs)
+    return true;
+  return false;
+}
+
+// src/index.ts
+var VERSION2 = "0.1.0";
+export {
+  writeStatus,
+  writeMeta,
+  writeAuthState,
+  withRetry,
+  updateMeta,
+  resolveAuthKey,
+  resolveArtifactPaths,
+  releaseLock,
+  readStatus,
+  readMeta,
+  readLock,
+  readAuthState,
+  rankStoryCandidates,
+  parseDuration,
+  needsRefresh,
+  loadConfig,
+  isLockStale,
+  hashString,
+  hashFileIfExists,
+  hashFile,
+  generateRunId,
+  generateKey,
+  forceUnlock,
+  encrypt,
+  defineConfig,
+  decrypt,
+  createJiraClient,
+  appendHistory,
+  acquireLock,
+  XeraConfigSchema,
+  VERSION2 as VERSION,
+  StatusJsonSchema,
+  NdjsonLogger,
+  MetaJsonSchema,
+  HistoryEntrySchema,
+  AuthStateEntrySchema,
+  AUTH_KEY_ENV
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xera-ai/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapter": {
+      "bun": "./src/adapter/types.ts",
+      "import": "./dist/adapter/types.js",
+      "types": "./dist/adapter/types.d.ts"
+    }
+  },
+  "bin": { "xera-internal": "./dist/bin/internal.js" },
+  "files": ["dist", "bin"],
+  "scripts": {
+    "build": "bun build ./src/index.ts ./bin/internal.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/web --external zod",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "3.23.8",
+    "@xera-ai/web": "workspace:*",
+    "@playwright/test": "1.48.0"
+  }
+}