braith 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,9 @@
 # braith
 
-Run `npx braith init` in your application repository, then follow `.braith/SETUP.md` with your coding agent. The CLI validates and publishes reviewed intent manifests; it does not upload your repository.
+Run `npx braith@0.3.0 connect` in your application repository, then follow `.braith/SETUP.md` with your coding agent. The CLI validates and publishes reviewed intent manifests; it does not upload your repository.
 
-Commands: `init`, `enroll`, `validate`, `push`, `release`, `test`.
+Commands: `connect`, `init`, `enroll`, `validate`, `push`, `release`, `test`.
 
-Use a short-lived enrollment prompt from the Braith dashboard to get scoped setup credentials. Keep `.braith/credentials.json` private. A pushed manifest is not active until you bind it to a release or explicitly select `release default`.
+Version 0.3.0 includes optional discovery context alongside configured outcomes. The coding tool installs supported capture across the app and creates a static catalogue, with findings visible in review mode. Discovery does not require a declared outcome for every flow. Capture/source changes enter the local review map; source files are not uploaded. The `test` command remains an isolated configured-outcome fixture, not a discovery accuracy test. Exercise actual hooks separately with normal, failed and recovered interactions.
+
+The setup prompt is public and identical for everyone. The CLI displays an expiring authorization link and code; approve the matching code in your signed-in Braith account. Only the waiting CLI receives scoped setup credentials. Run connect again to renew expired setup access. Keep `.braith/credentials.json` private. A pushed manifest is not active until you bind it to a release or explicitly select `release default`.

package/dist/cli.js

@@ -19860,6 +19860,99 @@ var DecisionRecordSchema = external_exports.object({
   }
 });
 
+// ../contracts/src/discovery.ts
+var DISCOVERY_EVENT = "braith_observation";
+var catalogue = (limit) => external_exports.record(IdentifierSchema, external_exports.string().trim().min(3).max(160)).refine(
+  (value) => Object.keys(value).length <= limit,
+  "Context catalogue too large"
+);
+var DiscoveryConfigSchema = external_exports.object({
+  enabled: external_exports.literal(true),
+  mode: external_exports.enum(["shadow", "review"]).default("review"),
+  application: external_exports.string().trim().min(10).max(600),
+  surfaces: catalogue(64).default({}),
+  actions: catalogue(128).default({}),
+  feedback: catalogue(64).default({})
+}).strict();
+var DiscoveryObservationSchema = external_exports.object({
+  kind: external_exports.enum([
+    "action",
+    "navigation",
+    "feedback",
+    "request",
+    "state",
+    "error"
+  ]),
+  surface: IdentifierSchema,
+  action: IdentifierSchema.optional(),
+  feedback: IdentifierSchema.optional(),
+  result: external_exports.enum([
+    "started",
+    "success",
+    "failure",
+    "pending",
+    "changed",
+    "unchanged",
+    "denied",
+    "cancelled",
+    "unknown"
+  ]),
+  httpStatus: external_exports.number().int().min(100).max(599).optional(),
+  contentKind: external_exports.enum(["html", "json", "file", "empty", "other"]).optional(),
+  position: external_exports.number().int().min(0).max(31),
+  end: external_exports.boolean()
+}).strict();
+var DiscoveryEvidenceSchema = DiscoveryObservationSchema.extend({
+  eventId: external_exports.string().min(1).max(256),
+  occurredAt: IsoDateTimeSchema,
+  sourceTrust: SourceTrustSchema
+}).strict();
+var DiscoveryStateSchema = external_exports.object({
+  schemaVersion: external_exports.literal(1),
+  context: DiscoveryConfigSchema,
+  observations: external_exports.array(DiscoveryEvidenceSchema).min(2).max(32)
+}).strict().superRefine((value, ctx) => {
+  const ids = /* @__PURE__ */ new Set();
+  value.observations.forEach((item, index) => {
+    if (ids.has(item.eventId) || item.position !== index || item.end !== (index === value.observations.length - 1))
+      ctx.addIssue({
+        code: "custom",
+        message: "Discovery requires a complete ordered window"
+      });
+    ids.add(item.eventId);
+  });
+});
+var DiscoveryDecisionSchema = external_exports.object({
+  assessment: external_exports.enum(["ordinary", "possible_problem", "insufficient"]),
+  confidence: external_exports.number().min(0).max(1),
+  problemProbability: external_exports.number().min(0).max(1),
+  category: external_exports.enum([
+    "contradiction",
+    "friction",
+    "access",
+    "data_loss",
+    "delivery",
+    "other",
+    "none"
+  ]),
+  severity: external_exports.enum(["low", "medium", "high", "critical"]),
+  evidenceStart: external_exports.string().min(1).max(256).nullable(),
+  evidenceEnd: external_exports.string().min(1).max(256).nullable()
+}).strict();
+var DiscoveryResultSchema = external_exports.discriminatedUnion("status", [
+  external_exports.object({
+    kind: external_exports.literal("discovery"),
+    status: external_exports.literal("evaluated"),
+    decision: DiscoveryDecisionSchema,
+    usage: ModelUsageSchema
+  }).strict(),
+  external_exports.object({
+    kind: external_exports.literal("discovery"),
+    status: external_exports.literal("unavailable"),
+    reason: external_exports.string().min(1).max(200)
+  }).strict()
+]);
+
 // ../contracts/src/events.ts
 var EventNameSchema = external_exports.string().trim().min(1).max(128).regex(/^[a-z][a-z0-9_]*$/, "Event names must use lower_snake_case");
 var EventBaseSchema = external_exports.object({
@@ -19883,7 +19976,16 @@ function requireSubject(value, ctx) {
     });
   }
 }
-var EventInputSchema = EventBaseSchema.superRefine(requireSubject);
+var EventInputSchema = EventBaseSchema.superRefine((event, ctx) => {
+  requireSubject(event, ctx);
+  if (Object.keys(event.properties).length > 24 || new TextEncoder().encode(JSON.stringify(event.properties)).byteLength > 1024 || new TextEncoder().encode(JSON.stringify(event)).byteLength > 4096) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["properties"],
+      message: "Events allow at most 24 properties, 1 KiB of properties and 4 KiB total"
+    });
+  }
+});
 var AcceptedEventSchema = EventBaseSchema.extend({
   projectId: OpaqueIdSchema,
   environment: EnvironmentSchema,
@@ -20088,6 +20190,9 @@ var EventDefinitionSchema = external_exports.object({
   allowedProperties: external_exports.record(IdentifierSchema, PropertyTypeSchema),
   requiredProperties: external_exports.array(IdentifierSchema).max(24)
 }).superRefine((definition, ctx) => {
+  if (Object.keys(definition.allowedProperties).length > 24) {
+    ctx.addIssue({ code: "custom", path: ["allowedProperties"], message: "At most 24 properties are supported" });
+  }
   for (const property of definition.requiredProperties) {
     if (!(property in definition.allowedProperties)) {
       ctx.addIssue({
@@ -20145,9 +20250,19 @@ var ProjectManifestSchema = external_exports.object({
   schemaVersion: external_exports.literal(1),
   manifestVersion: external_exports.string().trim().min(1).max(128),
   projectKey: external_exports.string().trim().min(1).max(256),
-  eventDefinitions: external_exports.array(EventDefinitionSchema).min(1).max(250),
-  intents: external_exports.array(IntentDefinitionSchema).min(1).max(15)
+  eventDefinitions: external_exports.array(EventDefinitionSchema).max(250),
+  intents: external_exports.array(IntentDefinitionSchema).max(15),
+  discovery: DiscoveryConfigSchema.optional()
 }).superRefine((manifest, ctx) => {
+  if (!manifest.discovery && (!manifest.intents.length || !manifest.eventDefinitions.length)) {
+    ctx.addIssue({ code: "custom", message: "A manifest needs configured outcomes or enabled discovery" });
+  }
+  if (manifest.eventDefinitions.some((event) => event.name === DISCOVERY_EVENT)) {
+    ctx.addIssue({ code: "custom", message: "braith_observation is reserved for validated discovery capture" });
+  }
+  if (new TextEncoder().encode(JSON.stringify(manifest)).byteLength > 65536) {
+    ctx.addIssue({ code: "custom", message: "Manifest exceeds the 64 KiB delivery limit" });
+  }
   const eventMap = new Map(manifest.eventDefinitions.map((event) => [event.name, event]));
   if (eventMap.size !== manifest.eventDefinitions.length) {
     ctx.addIssue({
@@ -20558,17 +20673,17 @@ function localCredentials(root) {
 }
 var setupInstructions = `# Set up Braith
 
-Instrument the application's important user outcomes using the Braith SDK.
+Install continual customer-problem discovery and stronger checks for the application's important outcomes. Inspect the repository locally; the developer should not have to define each flow.
 
-1. Inspect the repository and identify 3\u20135 critical user-facing outcomes. Prefer outcomes tied to activation, payment, retained access, data creation, export, invitation, or integration setup.
-2. For each outcome, describe the observable success boundary. A UI success message is not enough when the outcome depends on committed server state.
-3. Identify meaningful entry, progress, success, contradiction, recovery, and explicit cancellation signals. For each outcome, include at least one repeatable post-success contradiction when one exists (for example, an upgrade prompt after payment, a created project returning Not Found, or an export opening empty). Jev can interpret these ambiguous signals, but the incident policy still needs them declared. Do not instrument every interaction.
+1. Inspect the repository's routes, shared UI components, feedback and request/state boundaries. Create a static discovery catalogue in braith.config.json: enabled true, mode review, application purpose, surfaces, actions and feedback. These are descriptions of what the app does, not rules listing possible failures. Configure the SDK's discovery catalogue, route templates and stable action/feedback selectors. Cover supported app surfaces, including flows without configured outcomes. Never derive catalogue labels from customer content, URL parameters or form values.
+2. Alongside broad discovery, choose a few critical outcomes for stronger explicit checks. Describe their observable success boundary. A UI success message is not enough when the outcome depends on committed server state.
+3. Add finite observations at shared server/job/access/state boundaries where browser status alone cannot reveal the result. Use client.observeWindow on the server for a coherent same-subject sequence, or Braith.observe in the browser for a safe semantic summary. Use only catalogue identifiers and fixed kind/result/status/contentKind fields; never send values or request/response bodies. A local before/after comparison may report changed or unchanged without sending the underlying data. Automatic browser capture handles supported clicks, submits, navigation, same-origin fetch summaries and declared feedback selectors. It does not read page text, inspect network bodies, or prove that every feature is covered.
 4. Add allowlisted Braith events at those code locations. In browser code, use the named Braith export from @braith/sdk and call Braith.init({ projectKey, endpoint }) once, then Braith.identify and Braith.track. On the server, use createServerClient({ projectKey, endpoint }), pass userId and attemptId in track context, and flush before a short-lived process exits. Use server events for authoritative facts and propagate an attemptId across the journey.
-5. Replace the example in braith.config.json with the resulting event definitions and intents. Keep the set to 3\u20135 outcomes initially.
-6. Run the short-lived Braith enrollment command from the dashboard prompt. It stores keys only in .braith/credentials.json, ignored by .braith/.gitignore. For a later setup prompt, run braith enroll <token> --replace; the old local file is retained if renewal fails. Set the browser and server project keys in the corresponding application deployment environment. Never commit the server key. The temporary management key expires after 30 minutes.
+5. Additionally identify 3\u20135 critical user-facing outcomes, or fewer when appropriate, for stronger explicit checks. Define entry, authoritative success, progress, contradiction, recovery and cancellation signals. A UI success message alone cannot establish committed server state. Replace the example event definitions and intents with these real outcomes. Their absence must not exclude other activity from discovery; discovery-only apps may have empty arrays. Broad capture is opt-in, defaults to shadow review, and uses the existing event/analysis allowance: 20% of analysis capacity for discovery and 80% for core checks. Start at 10% ordinary-window sampling and at most 10 windows/hour per browser; observed failures are prioritised within that same cap. State coverage gaps and privacy choices honestly.
+6. Run braith connect and show the owner its authorization link and matching code. The owner signs in to Braith and approves that connection. Keys are stored only in .braith/credentials.json, ignored by .braith/.gitignore. Run connect again to renew setup access; existing credentials are preserved on failure or a different-project selection. Set browser and server keys in the corresponding deployment environment. Never commit the server key. The temporary management key expires after 30 minutes.
 7. Run npx braith validate, resolve errors, and review every warning or unverifiable source check.
 8. Present the instrumentation and configuration diff to the developer for review. Do not upload the repository or deploy automatically.
-9. After review, run npx braith push, then npx braith test. Push records .braith/source-map.json, a local review map of intent IDs to source files and hashes; it uploads only the manifest. Commit and review that map with the instrumentation. Use npx braith test --semantic to check a configured browser-contradiction journey with Jev. Test incidents are isolated from production usage and alerts.
+9. After review, run npx braith push. If core outcomes are configured, run npx braith test (and --semantic where supported). These isolated fixtures check configured-outcome plumbing, not discovery accuracy. Exercise real discovery hooks locally with normal, failed and recovered interactions; inspect sanitised payloads without exposing secrets. Push records .braith/source-map.json, a local review map of outcome and discovery source files and hashes; it uploads only the manifest. Commit and review that map with the instrumentation. Do not present synthetic test incidents as proof of real coverage or model accuracy.
 10. Before deployment, run npx braith release <your-build-id> to bind this reviewed manifest to the exact release used in Braith.init({ release }). For applications that cannot supply release metadata, explicitly run npx braith release default after review. New pushes never silently activate. A rollback binds a new build ID to the previous manifest version; do not rewrite an existing release binding.
 11. When a monitored workflow changes in a later release, validate again. A changed mapped source file or config requires a new manifestVersion, review of the affected code-to-outcome mapping, and another push before release binding. This hash check is only a reminder: code outside mapped files may affect outcomes, so inspect the whole workflow. Keep the previous manifest available for attempts already in progress. Never redefine success to make a regression look healthy.
 `;
@@ -20576,6 +20691,14 @@ var exampleConfig = {
   schemaVersion: 1,
   manifestVersion: "local-v1",
   projectKey: "env:BRAITH_PROJECT_KEY",
+  discovery: {
+    enabled: true,
+    mode: "review",
+    application: "A subscription app where customers pay for access to reporting tools.",
+    surfaces: { billing: "Choose a plan and pay for access", reports: "Use reports included in the selected plan" },
+    actions: { upgrade: "Upgrade the account", open_report: "Open a report" },
+    feedback: { upgraded: "The app reports paid access is active", upgrade_required: "The app asks the customer to upgrade for access" }
+  },
   eventDefinitions: [
     {
       name: "checkout_started",
@@ -20639,6 +20762,10 @@ function writeNew(path, contents) {
   writeFileSync(path, contents, "utf8");
   return true;
 }
+function ensureCredentialIgnore(directory) {
+  const path = join(directory, ".gitignore"), existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (!existing.split(/\r?\n/).some((line) => line.trim() === CREDENTIALS_NAME)) writeFileSync(path, existing + (existing && !existing.endsWith("\n") ? "\n" : "") + CREDENTIALS_NAME + "\n", "utf8");
+}
 function initProject(root = process.cwd()) {
   const directory = join(root, ".braith");
   mkdirSync(directory, { recursive: true });
@@ -20680,6 +20807,10 @@ function buildSourceMap(root, manifest) {
   }));
   const intents = {};
   const files = {};
+  const discovery = manifest.discovery ? sources.filter(
+    (source) => /\b(discovery|observeWindow|observe|catalogue)\b/.test(source.contents) && /braith/i.test(source.contents)
+  ).map((source) => source.path) : void 0;
+  for (const path of discovery ?? []) files[path] = sha256(sources.find((source) => source.path === path).contents);
   for (const intent of manifest.intents) {
     const names = new Set([
       ...intent.entrySignals,
@@ -20700,6 +20831,7 @@ function buildSourceMap(root, manifest) {
     manifestVersion: manifest.manifestVersion,
     configHash: sha256(readFileSync(join(root, CONFIG_NAME), "utf8")),
     intents,
+    ...discovery ? { discovery } : {},
     files
   };
 }
@@ -20770,6 +20902,7 @@ function validateProject(root = process.cwd()) {
     if (!/(createBrowserClient|createServerClient|Braith\.init)\s*\(/.test(source)) {
       messages.push({ level: "warning", message: "Braith SDK initialization was not found in source" });
     }
+    if (manifest.discovery && !/\b(discovery|observeWindow)\b/.test(source)) messages.push({ level: "unable", message: "Discovery is enabled but no capture configuration or server observation reference was found. This scan does not prove coverage." });
     for (const event of manifest.eventDefinitions) {
       if (!source.includes(event.name)) {
         messages.push({ level: "unable", message: `${event.name}: no source reference was found; wrappers or generated code may hide it` });
@@ -20782,8 +20915,7 @@ async function enrollProject(token, root = process.cwd(), replace = false) {
   if (!/^br_enroll_[A-Za-z0-9_-]{32}$/.test(token)) throw new Error("Invalid enrollment token");
   const directory = join(root, ".braith");
   mkdirSync(directory, { recursive: true });
-  writeNew(join(directory, ".gitignore"), `${CREDENTIALS_NAME}
-`);
+  ensureCredentialIgnore(directory);
   const path = join(directory, CREDENTIALS_NAME);
   if (existsSync(path) && !replace) {
     throw new Error("Existing enrollment found. Use braith enroll <token> --replace to renew setup access without deleting credentials by hand");
@@ -20817,6 +20949,43 @@ async function enrollProject(token, root = process.cwd(), replace = false) {
   }
   return { projectId: credentials.projectId, expiresAt: credentials.expiresAt };
 }
+async function connectProject(root = process.cwd()) {
+  const previous = localCredentials(root), apiUrl = (process.env.BRAITH_API_URL?.trim() || "https://app.braith.dev").replace(/\/$/, "");
+  const origin = new URL(apiUrl);
+  if (origin.protocol !== "https:" && !["127.0.0.1", "localhost"].includes(origin.hostname)) throw new Error("Braith connection requires HTTPS");
+  const call = (body) => fetch(apiUrl + "/api/v1/setup", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(15e3), redirect: "error" });
+  const start = await call({ action: "start" });
+  if (!start.ok) throw new Error("Braith connection is unavailable. Try again shortly.");
+  const pending = await start.json();
+  if (!/^br_device_[A-Za-z0-9_-]{32}$/.test(pending.deviceToken) || !Number.isFinite(pending.expiresIn) || pending.expiresIn <= 0 || pending.expiresIn > 900 || new URL(pending.verificationUrl).origin !== origin.origin || !Number.isFinite(pending.interval) || pending.interval < 5 || pending.interval > 30) throw new Error("Invalid Braith connection response");
+  console.log("Approve this connection in Braith: " + pending.verificationUrl + "\nCheck that the code matches: " + pending.userCode + "\nWaiting for your approval\u2026");
+  const deadline = Date.now() + pending.expiresIn * 1e3;
+  while (Date.now() < deadline) {
+    await new Promise((resolve2) => setTimeout(resolve2, pending.interval * 1e3));
+    if (Date.now() >= deadline) break;
+    const response = await call({ action: "poll", deviceToken: pending.deviceToken });
+    if (response.status === 202) continue;
+    if (response.status === 429) {
+      await new Promise((resolve2) => setTimeout(resolve2, 3e4));
+      continue;
+    }
+    if (!response.ok) throw new Error("Connection cancelled or expired. Run braith connect again.");
+    const value = await response.json();
+    if (![value.projectId, value.browserKey, value.serverKey, value.managementKey, value.expiresAt].every((item) => typeof item === "string" && item.length > 0) || !Number.isFinite(Date.parse(value.expiresAt)) || Date.parse(value.expiresAt) <= Date.now()) throw new Error("Connection returned incomplete credentials");
+    if (previous && previous.projectId !== value.projectId) throw new Error("This connection is for a different app. Existing credentials were preserved.");
+    initProject(root);
+    ensureCredentialIgnore(join(root, ".braith"));
+    const path = join(root, ".braith", CREDENTIALS_NAME), temporary = path + "." + randomUUID() + ".tmp";
+    try {
+      writeFileSync(temporary, JSON.stringify({ ...value, apiUrl }, null, 2) + "\n", { encoding: "utf8", mode: 384, flag: "wx" });
+      renameSync(temporary, path);
+    } finally {
+      if (existsSync(temporary)) rmSync(temporary);
+    }
+    return { projectId: value.projectId, expiresAt: value.expiresAt };
+  }
+  throw new Error("Connection expired. Run braith connect again.");
+}
 function printValidation(result) {
   for (const message of result.messages) console.log(`${message.level.toUpperCase()}: ${message.message}`);
   console.log(result.valid ? "Braith configuration is valid." : "Braith configuration is invalid.");
@@ -20928,6 +21097,17 @@ async function testProject(root = process.cwd(), mode) {
 }
 async function run(argv = process.argv.slice(2), root = process.cwd()) {
   const command = argv[0];
+  if (command === "connect") {
+    try {
+      if (argv.length !== 1) throw new Error("Usage: braith connect");
+      await connectProject(root);
+      console.log("Connected. Follow .braith/SETUP.md to integrate this app.");
+      return 0;
+    } catch (error62) {
+      console.error(error62 instanceof Error ? error62.message : "Connection failed");
+      return 1;
+    }
+  }
   if (command === "init") {
     const result = initProject(root);
     for (const path of result.created) console.log(`Created ${path}`);
@@ -20985,13 +21165,14 @@ async function run(argv = process.argv.slice(2), root = process.cwd()) {
       return 1;
     }
   }
-  console.error("Usage: braith <init|enroll|validate|push|release|test>");
+  console.error("Usage: braith <connect|init|enroll|validate|push|release|test>");
   return 1;
 }
 var invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
 if (invokedPath === import.meta.url) process.exitCode = await run();
 export {
   bindRelease,
+  connectProject,
   enrollProject,
   initProject,
   pushProject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braith",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Braith coding-agent setup and outcome manifest CLI",
   "license": "UNLICENSED",
   "publishConfig": { "access": "public" },