@opice/cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@opice/cli",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "CLI for opice — scaffolds projects and wraps `bun test` to stream E2E results to the reporting platform",
 	"type": "module",
 	"bin": {

package/src/cli.ts

@@ -13,7 +13,7 @@ Commands:
       Scaffold opice.config.json in the current project. Pass
       --with-workflow to also drop a .github/workflows/opice.yml.
 
-  test [--retries=N] [--tier=NAME] [bun test args...]
+  test [--retries=N] [--tier=NAME] [--fail-on-report-error] [bun test args...]
       Wrapper around 'bun test' that exports OPICE_* env vars from
       opice.config.json + git so the harness reporter streams results
       to the platform. All trailing args pass through to bun test.
@@ -26,6 +26,11 @@ Commands:
       standard. Scenarios above it are reported "skipped", not run.
       Falls back to OPICE_TIER, then "tier" in opice.config.json;
       omit to run everything.
+      --fail-on-report-error exits non-zero if reporting to the platform
+      fails (default: reporting is best-effort and never reddens CI).
+      Use it so a bad token / unreachable endpoint can't leave CI green
+      while nothing reaches the dashboard. Falls back to
+      OPICE_REPORT_STRICT, then "failOnReportError" in opice.config.json.
 
   failures <run-url|run-id> [--json]
       Pull a failed run's details (failed scenarios, the failing step,

package/src/commands/failures.ts

@@ -5,10 +5,11 @@
  * source test file that produced them (the test is the spec — each step
  * carries its `intent`, so there's no separate scenario file).
  *
- * Reads are token-gated. The read token (and endpoint/project) come from, in
- * order: the URL's `?token=` when you paste a dashboard link, OPICE_READ_TOKEN,
- * or OPICE_READ_DSN (the self-contained `https://<readKey>@host/slug` the
- * dashboard hands out at project creation).
+ * Two read modes:
+ *   - SERVICE TOKEN (OPICE_READ_DSN): a propustka service-token principal → REST
+ *     GET /api/v1/<slug>/… with the CF-Access-Client-* headers.
+ *   - CAPABILITY SHARE: a pasted dashboard link's `?token=` (or OPICE_READ_TOKEN)
+ *     → the anonymous read RPC at /s/rpc.
  */
 
 import { loadConfig } from '../config'
@@ -45,10 +46,18 @@ interface Step {
 interface Target {
 	endpoint: string
 	runId: string
-	token: string | undefined
 	slug?: string
+	// Exactly one auth mode: a pasted share link / OPICE_READ_TOKEN is a capability on /s/rpc;
+	// OPICE_READ_DSN is a service token (CF-Access-Client-*) on /api/v1.
+	shareToken?: string
+	service?: { clientId: string; clientSecret: string }
 }
 
+type ReadOp =
+	| { kind: 'run'; runId: string }
+	| { kind: 'scenarios'; runId: string }
+	| { kind: 'steps'; scenarioId: string }
+
 export async function failuresCommand(args: string[]): Promise<number> {
 	const asJson = args.includes('--json')
 	const positional = args.filter((a) => !a.startsWith('--'))
@@ -67,8 +76,8 @@ export async function failuresCommand(args: string[]): Promise<number> {
 	let run: Run
 	let scenarios: Scenario[]
 	try {
-		run = await rpc<Run>(target, 'runs.get', { runId: target.runId })
-		scenarios = await rpc<Scenario[]>(target, 'runs.scenarios', { runId: target.runId })
+		run = await read<Run>(target, { kind: 'run', runId: target.runId })
+		scenarios = await read<Scenario[]>(target, { kind: 'scenarios', runId: target.runId })
 	} catch (err) {
 		console.error(`[opice] ${(err as Error).message}`)
 		return 1
@@ -78,7 +87,7 @@ export async function failuresCommand(args: string[]): Promise<number> {
 	const detailed = await Promise.all(
 		failed.map(async (s) => ({
 			scenario: s,
-			steps: await rpc<Step[]>(target, 'scenarios.steps', { scenarioId: s.id }).catch(() => [] as Step[]),
+			steps: await read<Step[]>(target, { kind: 'steps', scenarioId: s.id }).catch(() => [] as Step[]),
 		})),
 	)
 
@@ -141,37 +150,68 @@ function printDigest(run: Run, detailed: { scenario: Scenario; steps: Step[] }[]
 
 function absoluteScreenshot(relativeOrAbsolute: string, target: Target): string {
 	const base = relativeOrAbsolute.startsWith('http') ? relativeOrAbsolute : `${target.endpoint}${relativeOrAbsolute}`
-	if (!target.token) return base
-	return `${base}${base.includes('?') ? '&' : '?'}token=${target.token}`
+	// A share link can carry its token in the URL; a service token needs headers, so leave it bare.
+	if (!target.shareToken) return base
+	return `${base}${base.includes('?') ? '&' : '?'}token=${target.shareToken}`
 }
 
 async function resolveTarget(ref: string): Promise<Target | null> {
 	const readDsn = parseOpiceDsn(process.env['OPICE_READ_DSN'])
-	const envToken = process.env['OPICE_READ_TOKEN'] ?? readDsn?.apiKey ?? undefined
+	const service = readDsn ? { clientId: readDsn.clientId, clientSecret: readDsn.clientSecret } : undefined
+	const envShareToken = process.env['OPICE_READ_TOKEN']
 
 	if (/^https?:\/\//.test(ref)) {
 		const url = new URL(ref)
-		const token = url.searchParams.get('token') ?? envToken
+		const urlToken = url.searchParams.get('token')
 		const match = url.pathname.match(/\/p\/([^/]+)\/r\/([^/]+)/)
-		if (match) {
-			return { endpoint: url.origin, runId: decodeURIComponent(match[2]!), token, slug: decodeURIComponent(match[1]!) }
-		}
-		// Fall back to the last path segment as the run id.
-		const segments = url.pathname.split('/').filter(Boolean)
-		const runId = segments[segments.length - 1]
-		if (runId) return { endpoint: url.origin, runId, token }
-		return null
+		const slug = match ? decodeURIComponent(match[1]!) : (process.env['OPICE_PROJECT'] ?? readDsn?.project)
+		const runId = match ? decodeURIComponent(match[2]!) : url.pathname.split('/').filter(Boolean).pop()
+		if (!runId) return null
+		// A pasted share link (?token=) or OPICE_READ_TOKEN → capability; otherwise the read DSN.
+		const shareToken = urlToken ?? envShareToken
+		if (shareToken) return { endpoint: url.origin, runId, slug, shareToken }
+		return { endpoint: url.origin, runId, slug, service }
 	}
 
-	// Bare run id — endpoint from config/env/DSN, token from env/read DSN.
+	// Bare run id — endpoint + slug from config/env/DSN, auth from the read DSN or OPICE_READ_TOKEN.
 	const config = await loadConfig()
 	const endpoint = process.env['OPICE_ENDPOINT'] ?? config?.endpoint ?? readDsn?.endpoint ?? parseOpiceDsn(process.env['OPICE_DSN'])?.endpoint
 	if (!endpoint) return null
-	return { endpoint, runId: ref, token: envToken }
+	const slug = process.env['OPICE_PROJECT'] ?? config?.project ?? readDsn?.project
+	if (envShareToken) return { endpoint, runId: ref, slug, shareToken: envShareToken }
+	return { endpoint, runId: ref, slug, service }
 }
 
-async function rpc<T>(target: Target, method: string, input: unknown): Promise<T> {
-	const url = `${target.endpoint}/s/rpc${target.token ? `?token=${target.token}` : ''}`
+/**
+ * Read one resource, routed by the target's auth mode: a service token → REST GET on /api/v1
+ * (which needs the project slug); a capability share token → the /s/rpc read RPC.
+ */
+async function read<T>(target: Target, op: ReadOp): Promise<T> {
+	if (target.service) {
+		if (!target.slug) {
+			throw new Error('reading via OPICE_READ_DSN needs the project slug — paste a full run URL or set OPICE_PROJECT')
+		}
+		const path = op.kind === 'run'
+			? `runs/${op.runId}`
+			: op.kind === 'scenarios'
+				? `runs/${op.runId}/scenarios`
+				: `scenarios/${op.scenarioId}/steps`
+		const response = await fetch(`${target.endpoint}/api/v1/${target.slug}/${path}`, {
+			headers: {
+				'cf-access-client-id': target.service.clientId,
+				'cf-access-client-secret': target.service.clientSecret,
+			},
+		})
+		if (!response.ok) {
+			throw new Error(`${op.kind}: ${response.status} ${response.statusText}`)
+		}
+		return (await response.json()) as T
+	}
+
+	// Capability share → the anonymous read RPC.
+	const method = op.kind === 'run' ? 'runs.get' : op.kind === 'scenarios' ? 'runs.scenarios' : 'scenarios.steps'
+	const input = op.kind === 'steps' ? { scenarioId: op.scenarioId } : { runId: op.runId }
+	const url = `${target.endpoint}/s/rpc${target.shareToken ? `?token=${target.shareToken}` : ''}`
 	const response = await fetch(url, {
 		method: 'POST',
 		headers: { 'content-type': 'application/json' },

package/src/commands/test.ts

@@ -12,7 +12,9 @@ interface Handoff {
 	endpoint: string
 	/** Project slug — used to build the /api/v1/<project>/runs/<id>/finish URL. */
 	project: string
-	apiKey: string
+	/** Service-token credentials for the CF-Access-Client-* headers on POST /finish. */
+	clientId: string
+	clientSecret: string
 	runId: string
 }
 
@@ -21,7 +23,8 @@ export async function testCommand(args: string[]): Promise<number> {
 	const dsn = parseOpiceDsn(process.env['OPICE_DSN'])
 	const project = process.env['OPICE_PROJECT'] ?? config?.project ?? dsn?.project
 	const endpoint = process.env['OPICE_ENDPOINT'] ?? config?.endpoint ?? dsn?.endpoint
-	const apiKey = process.env['OPICE_API_KEY'] ?? dsn?.apiKey
+	const clientId = process.env['OPICE_CLIENT_ID'] ?? dsn?.clientId
+	const clientSecret = process.env['OPICE_CLIENT_SECRET'] ?? dsn?.clientSecret
 
 	if (!project) {
 		warn('OPICE_PROJECT not set and no opice.config.json found. Run `opice init` or set the env var.')
@@ -29,8 +32,8 @@ export async function testCommand(args: string[]): Promise<number> {
 	if (!endpoint) {
 		warn('OPICE_ENDPOINT not set and no opice.config.json found. Tests will run without reporting.')
 	}
-	if (!apiKey) {
-		warn('OPICE_API_KEY not set. Tests will run without reporting.')
+	if (!clientId || !clientSecret) {
+		warn('OPICE_CLIENT_ID / OPICE_CLIENT_SECRET not set (the OPICE_DSN userinfo). Tests will run without reporting.')
 	}
 
 	// `--tier=NAME` selects which test tier runs (critical < standard < extended).
@@ -40,23 +43,33 @@ export async function testCommand(args: string[]): Promise<number> {
 	const { tier, rest: afterTier } = extractTier(args)
 	const resolvedTier = tier ?? process.env['OPICE_TIER'] ?? config?.tier
 
+	// `--fail-on-report-error` turns a swallowed reporting failure into a non-zero
+	// exit (default is best-effort: reporting never reddens CI). CLI flag wins over
+	// OPICE_REPORT_STRICT, which wins over opice.config.json's `failOnReportError`.
+	// We propagate it to the harness via OPICE_REPORT_STRICT (it fails the run from
+	// a scenario's afterAll) AND honour it here for the POST /finish finalize.
+	const { strict: strictFlag, rest: afterStrict } = extractStrict(afterTier)
+	const strict = strictFlag || isTruthy(process.env['OPICE_REPORT_STRICT']) || config?.failOnReportError === true
+
 	const git = detectGitMeta()
 	const env: NodeJS.ProcessEnv = {
 		...process.env,
 		...(project ? { OPICE_PROJECT: project } : {}),
 		...(endpoint ? { OPICE_ENDPOINT: endpoint } : {}),
-		// Resolve the api key (incl. from a DSN) into the explicit var the
+		// Resolve the service-token pair (incl. from a DSN) into the explicit vars the
 		// harness reporter reads, so a bare OPICE_DSN is enough to report.
-		...(apiKey ? { OPICE_API_KEY: apiKey } : {}),
+		...(clientId ? { OPICE_CLIENT_ID: clientId } : {}),
+		...(clientSecret ? { OPICE_CLIENT_SECRET: clientSecret } : {}),
 		...(git.branch ? { OPICE_BRANCH: git.branch } : {}),
 		...(git.commit ? { OPICE_COMMIT: git.commit } : {}),
 		...(resolvedTier ? { OPICE_TIER: resolvedTier } : {}),
+		...(strict ? { OPICE_REPORT_STRICT: '1' } : {}),
 	}
 
 	// `--retries=N` (opice's spelling) → bun's `--retry=N`, the global default
 	// retry budget for every scenario. CLI flag wins over opice.config.json's
 	// `retries`. A per-scenario `walkthrough`/meta `retries` overrides both.
-	const { retries, rest } = extractRetries(afterTier)
+	const { retries, rest } = extractRetries(afterStrict)
 	const resolvedRetries = retries ?? config?.retries
 	const bunArgs = ['test', ...rest]
 	// Don't clobber an explicit `--retry` the caller passed through to bun.
@@ -72,7 +85,16 @@ export async function testCommand(args: string[]): Promise<number> {
 
 	// After bun test exits, look for handoff files the reporter wrote and
 	// POST /finish for each run so it leaves "running" state.
-	await finalizeHandoffs(child.pid, project)
+	const finalizeFailed = await finalizeHandoffs(child.pid, project)
+
+	// Under strict reporting, a failed finalize (POST /finish) reddens an
+	// otherwise-green run — the same contract the harness enforces for in-test
+	// reports. Don't mask a real test failure: only escalate when bun itself was
+	// green. (An in-test report failure already failed bun via the harness.)
+	if (exitCode === 0 && strict && finalizeFailed) {
+		warn('reporting failed and --fail-on-report-error is set — exiting non-zero.')
+		return 1
+	}
 
 	return exitCode
 }
@@ -131,14 +153,38 @@ function extractTier(args: string[]): { tier: string | undefined; rest: string[]
 	return { tier, rest }
 }
 
-async function finalizeHandoffs(childPid: number | undefined, slug: string | undefined): Promise<void> {
+/** Returns true if finalizing any run failed (so strict mode can escalate). */
+/**
+ * Pull opice's `--fail-on-report-error` boolean flag out of the arg list (it's
+ * an opice concept, not a bun flag) and return whether it was present plus the
+ * remaining args.
+ */
+function extractStrict(args: string[]): { strict: boolean; rest: string[] } {
+	const rest: string[] = []
+	let strict = false
+	for (const arg of args) {
+		if (arg === '--fail-on-report-error') strict = true
+		else rest.push(arg)
+	}
+	return { strict, rest }
+}
+
+function isTruthy(value: string | undefined): boolean {
+	if (!value) return false
+	const v = value.toLowerCase()
+	return v === '1' || v === 'true' || v === 'yes' || v === 'on'
+}
+
+/** Returns true if finalizing any run failed (so strict mode can escalate). */
+async function finalizeHandoffs(childPid: number | undefined, slug: string | undefined): Promise<boolean> {
 	let files: string[]
 	try {
 		files = await fs.readdir(HANDOFF_DIR)
 	} catch {
-		return // no handoff dir → no runs reported, nothing to finalize
+		return false // no handoff dir → no runs reported, nothing to finalize
 	}
 	const matching = childPid ? files.filter((f) => f === `${childPid}.json`) : files
+	let failed = false
 	for (const file of matching) {
 		const full = path.join(HANDOFF_DIR, file)
 		try {
@@ -146,11 +192,13 @@ async function finalizeHandoffs(childPid: number | undefined, slug: string | und
 			await finishRun(handoff)
 			printRunUrl(handoff, slug)
 		} catch (err) {
+			failed = true
 			warn(`Failed to finalize run from ${file}: ${(err as Error).message}`)
 		} finally {
 			await fs.unlink(full).catch(() => {})
 		}
 	}
+	return failed
 }
 
 function printRunUrl(handoff: Handoff, slug: string | undefined): void {
@@ -164,7 +212,10 @@ async function finishRun(handoff: Handoff): Promise<void> {
 	const url = `${handoff.endpoint}/api/v1/${handoff.project}/runs/${handoff.runId}/finish`
 	const response = await fetch(url, {
 		method: 'POST',
-		headers: { authorization: `Bearer ${handoff.apiKey}` },
+		headers: {
+			'cf-access-client-id': handoff.clientId,
+			'cf-access-client-secret': handoff.clientSecret,
+		},
 	})
 	if (!response.ok) {
 		throw new Error(`${response.status} ${await response.text()}`)

package/src/config.ts

@@ -18,6 +18,14 @@ export interface OpiceConfig {
 	 * Scenarios above the selected tier are reported `skipped`, not run.
 	 */
 	tier?: 'critical' | 'standard' | 'extended'
+	/**
+	 * Fail the run if reporting to the platform fails (default best-effort: a
+	 * reporting failure is logged but never reddens CI). When set, a failed report
+	 * during the test (harness) or a failed `POST /finish` (this CLI) exits
+	 * non-zero. Overridden by `opice test --fail-on-report-error` and the
+	 * `OPICE_REPORT_STRICT` env var.
+	 */
+	failOnReportError?: boolean
 }
 
 const CONFIG_NAME = 'opice.config.json'

package/src/dsn.ts

@@ -1,18 +1,20 @@
 /**
  * An opice DSN packs everything a project needs to report into one string:
  *
- *   OPICE_DSN=https://<apiKey>@<host>/<slug>
+ *   OPICE_DSN=https://<clientId>:<clientSecret>@<host>/<slug>
  *
- * The api key rides in the userinfo, the host is the platform endpoint, and
- * the first path segment is the project slug. The individual `OPICE_*` vars
- * (and opice.config.json) still win when present — the DSN is a convenience
- * fallback so the dashboard can hand out a single value to drop into `.env`.
+ * The DSN is a Cloudflare Access SERVICE TOKEN: the client id + secret ride in the
+ * userinfo (sent as `CF-Access-Client-Id` / `CF-Access-Client-Secret`), the host is
+ * the platform endpoint, and the first path segment is the project slug. The
+ * individual `OPICE_*` vars (and opice.config.json) still win when present — the DSN
+ * is a convenience fallback so the dashboard can hand out a single value.
  *
  * Kept in sync with `@opice/harness`'s copy; duplicated to avoid a CLI→harness
  * dependency.
  */
 export interface OpiceDsn {
-	apiKey: string
+	clientId: string
+	clientSecret: string
 	endpoint: string
 	project: string
 }
@@ -25,8 +27,9 @@ export function parseOpiceDsn(raw: string | undefined | null): OpiceDsn | null {
 	} catch {
 		return null
 	}
-	const apiKey = decodeURIComponent(url.username)
+	const clientId = decodeURIComponent(url.username)
+	const clientSecret = decodeURIComponent(url.password)
 	const project = url.pathname.replace(/^\/+/, '').split('/')[0] ?? ''
-	if (!apiKey || !project) return null
-	return { apiKey, endpoint: `${url.protocol}//${url.host}`, project }
+	if (!clientId || !clientSecret || !project) return null
+	return { clientId, clientSecret, endpoint: `${url.protocol}//${url.host}`, project }
 }