@opice/cli 0.0.1

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@opice/cli",
+	"version": "0.0.1",
+	"description": "CLI for opice — scaffolds projects and wraps `bun test` to stream E2E results to the reporting platform",
+	"type": "module",
+	"bin": {
+		"opice": "src/cli.ts"
+	},
+	"exports": {
+		".": {
+			"types": "./src/cli.ts",
+			"default": "./src/cli.ts"
+		}
+	},
+	"files": [
+		"src"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"bun-types": "*"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/contember/opice.git",
+		"directory": "packages/cli"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/cli.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env bun
+import { failuresCommand } from './commands/failures'
+import { initCommand } from './commands/init'
+import { installSkillsCommand } from './commands/install-skills'
+import { testCommand } from './commands/test'
+import { usersCommand } from './commands/users'
+
+const HELP = `opice — AI-driven E2E browser test harness
+
+Usage: opice <command> [options]
+
+Commands:
+  init [--project=SLUG] [--endpoint=URL] [--with-workflow]
+      Scaffold opice.config.json in the current project. Pass
+      --with-workflow to also drop a .github/workflows/opice.yml.
+
+  test [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.
+
+  failures <run-url|run-id> [--json]
+      Pull a failed run's details (failed scenarios, the failing step,
+      error, screenshot URL, and source files) for the re-eval workflow.
+      Token comes from the URL's ?token= or OPICE_READ_TOKEN.
+
+  users create <email> [--password=...] [--name=...] [--endpoint=URL] [--admin-token=TOKEN]
+      Create a dashboard login (every user is admin). Needs the admin
+      token (--admin-token or OPICE_ADMIN_TOKEN) and the platform endpoint
+      (--endpoint, OPICE_ENDPOINT, or opice.config.json). A password is
+      generated and printed if you don't pass one.
+
+  install-skills [--global] [--ref=BRANCH]
+      Install opice's Claude Code skills + author agent into this project's
+      .claude/ (or ~/.claude with --global), fetched from GitHub. Restart
+      Claude Code afterwards to load them.
+
+  help
+      Show this message.
+`
+
+async function main(argv: string[]): Promise<number> {
+	const [command, ...rest] = argv
+	switch (command) {
+		case 'init':
+			return initCommand(parseInitFlags(rest))
+		case 'test':
+			return testCommand(rest)
+		case 'failures':
+			return failuresCommand(rest)
+		case 'users':
+			return usersCommand(rest)
+		case 'install-skills':
+			return installSkillsCommand(rest)
+		case 'help':
+		case '--help':
+		case '-h':
+		case undefined:
+			console.log(HELP)
+			return 0
+		default:
+			console.error(`Unknown command: ${command}`)
+			console.error(HELP)
+			return 1
+	}
+}
+
+function parseInitFlags(args: string[]): { project?: string; endpoint?: string; withWorkflow?: boolean } {
+	const flags: { project?: string; endpoint?: string; withWorkflow?: boolean } = {}
+	for (const arg of args) {
+		if (arg === '--with-workflow') flags.withWorkflow = true
+		else if (arg.startsWith('--project=')) flags.project = arg.slice('--project='.length)
+		else if (arg.startsWith('--endpoint=')) flags.endpoint = arg.slice('--endpoint='.length)
+	}
+	return flags
+}
+
+process.exit(await main(process.argv.slice(2)))

package/src/commands/failures.ts

@@ -0,0 +1,178 @@
+/**
+ * `opice failures <run-url|run-id>` — pull a failed run's details from the
+ * platform and print a digest the re-eval workflow can act on: which
+ * scenarios failed, at which step, the error, the screenshot URL, and the
+ * source files (test + scenario.md) that produced them.
+ *
+ * Reads are token-gated. The token is taken from the URL's `?token=` (when you
+ * paste a dashboard link) or from OPICE_READ_TOKEN.
+ */
+
+import { loadConfig } from '../config'
+import { parseOpiceDsn } from '../dsn'
+
+interface Run {
+	id: string
+	branch: string | null
+	commitSha: string | null
+	status: string
+	totalScenarios: number
+	passedScenarios: number
+	failedScenarios: number
+}
+
+interface Scenario {
+	id: string
+	name: string
+	hash: string | null
+	testFile: string | null
+	scenarioFile: string | null
+	status: string
+}
+
+interface Step {
+	id: number
+	sequence: number
+	name: string
+	status: string
+	error: string | null
+	screenshotUrl: string | null
+}
+
+interface Target {
+	endpoint: string
+	runId: string
+	token: string | undefined
+	slug?: string
+}
+
+export async function failuresCommand(args: string[]): Promise<number> {
+	const asJson = args.includes('--json')
+	const positional = args.filter((a) => !a.startsWith('--'))
+	const ref = positional[0]
+	if (!ref) {
+		console.error('Usage: opice failures <run-url|run-id> [--json]')
+		return 1
+	}
+
+	const target = await resolveTarget(ref)
+	if (!target) {
+		console.error('Could not determine the platform endpoint. Pass a full run URL or run `opice` from a project with opice.config.json.')
+		return 1
+	}
+
+	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 })
+	} catch (err) {
+		console.error(`[opice] ${(err as Error).message}`)
+		return 1
+	}
+
+	const failed = scenarios.filter((s) => s.status === 'failed')
+	const detailed = await Promise.all(
+		failed.map(async (s) => ({
+			scenario: s,
+			steps: await rpc<Step[]>(target, 'scenarios.steps', { scenarioId: s.id }).catch(() => [] as Step[]),
+		})),
+	)
+
+	if (asJson) {
+		console.log(JSON.stringify({ run, failures: detailed.map((d) => digestEntry(d, target)) }, null, 2))
+		return 0
+	}
+
+	printDigest(run, detailed, target)
+	return 0
+}
+
+function digestEntry(d: { scenario: Scenario; steps: Step[] }, target: Target) {
+	const failedSteps = d.steps.filter((s) => s.status === 'failed')
+	return {
+		name: d.scenario.name,
+		hash: d.scenario.hash,
+		testFile: d.scenario.testFile,
+		scenarioFile: d.scenario.scenarioFile,
+		stepCount: d.steps.length,
+		failedSteps: failedSteps.map((s) => ({
+			sequence: s.sequence,
+			name: s.name,
+			error: s.error,
+			screenshot: s.screenshotUrl ? absoluteScreenshot(s.screenshotUrl, target) : null,
+		})),
+	}
+}
+
+function printDigest(run: Run, detailed: { scenario: Scenario; steps: Step[] }[], target: Target): void {
+	const out: string[] = []
+	out.push(`Run ${run.id} — ${run.status.toUpperCase()}`)
+	const meta = [run.branch, run.commitSha ? `commit ${run.commitSha.slice(0, 7)}` : null].filter(Boolean).join(' · ')
+	if (meta) out.push(meta)
+	out.push(`${run.failedScenarios}/${run.totalScenarios} scenarios failed`)
+	out.push('')
+
+	if (detailed.length === 0) {
+		out.push('No failed scenarios recorded for this run.')
+		console.log(out.join('\n'))
+		return
+	}
+
+	for (const { scenario, steps } of detailed) {
+		const failedSteps = steps.filter((s) => s.status === 'failed')
+		out.push(`✗ ${scenario.name}${scenario.hash ? `  [#${scenario.hash}]` : ''}`)
+		if (scenario.testFile) out.push(`  test:     ${scenario.testFile}`)
+		if (scenario.scenarioFile) out.push(`  scenario: ${scenario.scenarioFile}`)
+		for (const s of failedSteps) {
+			out.push(`  failed at step ${s.sequence + 1}/${steps.length}: "${s.name}"`)
+			if (s.error) {
+				for (const line of s.error.split('\n')) out.push(`    ${line}`)
+			}
+			if (s.screenshotUrl) out.push(`    screenshot: ${absoluteScreenshot(s.screenshotUrl, target)}`)
+		}
+		out.push('')
+	}
+	console.log(out.join('\n').trimEnd())
+}
+
+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}`
+}
+
+async function resolveTarget(ref: string): Promise<Target | null> {
+	if (/^https?:\/\//.test(ref)) {
+		const url = new URL(ref)
+		const token = url.searchParams.get('token') ?? process.env['OPICE_READ_TOKEN'] ?? undefined
+		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
+	}
+
+	// Bare run id — endpoint from config/env/DSN, token from env.
+	const config = await loadConfig()
+	const endpoint = process.env['OPICE_ENDPOINT'] ?? config?.endpoint ?? parseOpiceDsn(process.env['OPICE_DSN'])?.endpoint
+	if (!endpoint) return null
+	return { endpoint, runId: ref, token: process.env['OPICE_READ_TOKEN'] ?? undefined }
+}
+
+async function rpc<T>(target: Target, method: string, input: unknown): Promise<T> {
+	const url = `${target.endpoint}/rpc${target.token ? `?token=${target.token}` : ''}`
+	const response = await fetch(url, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify({ method, input }),
+	})
+	const data = (await response.json().catch(() => null)) as { result?: T; error?: { message?: string } } | null
+	if (!data) throw new Error(`${method}: ${response.status} ${response.statusText}`)
+	if (data.error) throw new Error(`${method}: ${data.error.message ?? 'request failed'}`)
+	return data.result as T
+}

package/src/commands/init.ts

@@ -0,0 +1,84 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { loadConfig, writeConfig } from '../config'
+
+interface InitOptions {
+	project?: string
+	endpoint?: string
+	withWorkflow?: boolean
+}
+
+export async function initCommand(opts: InitOptions): Promise<number> {
+	const cwd = process.cwd()
+	const existing = await loadConfig(cwd)
+	if (existing) {
+		console.error(`opice.config.json already exists in this project (project=${existing.project}).`)
+		console.error('Edit it directly, or delete it and re-run init.')
+		return 1
+	}
+
+	const project = opts.project ?? prompt('Project slug:') ?? ''
+	if (!project) {
+		console.error('Project slug is required.')
+		return 1
+	}
+	const endpoint = opts.endpoint ?? prompt('Reporter endpoint (e.g. https://opice.example.com):') ?? ''
+	if (!endpoint) {
+		console.error('Endpoint is required.')
+		return 1
+	}
+
+	const configPath = await writeConfig(cwd, { project, endpoint })
+	console.log(`✓ Wrote ${path.relative(cwd, configPath)}`)
+
+	if (opts.withWorkflow) {
+		const workflowPath = await writeWorkflow(cwd)
+		console.log(`✓ Wrote ${path.relative(cwd, workflowPath)}`)
+	}
+
+	console.log()
+	console.log('Next steps:')
+	console.log('  1. Set OPICE_DSN (from the dashboard) in .env locally and as a CI repo secret.')
+	console.log('  2. Run your tests via `opice test <bun-test-args>` to stream results.')
+	return 0
+}
+
+async function writeWorkflow(cwd: string): Promise<string> {
+	const target = path.join(cwd, '.github', 'workflows', 'opice.yml')
+	await fs.mkdir(path.dirname(target), { recursive: true })
+	await fs.writeFile(target, WORKFLOW_TEMPLATE, 'utf-8')
+	return target
+}
+
+const WORKFLOW_TEMPLATE = `name: opice browser tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - name: Install agent-browser
+        run: bun add -g agent-browser
+      - name: Start playground (background)
+        run: bun run dev &
+        env:
+          NODE_ENV: development
+      - name: Wait for playground
+        run: |
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:5173 > /dev/null; then break; fi
+            sleep 1
+          done
+      - name: Run opice browser tests
+        run: bunx opice test tests/browser/
+        env:
+          OPICE_DSN: \${{ secrets.OPICE_DSN }}
+          PLAYGROUND_URL: http://localhost:5173
+`

package/src/commands/install-skills.ts

@@ -0,0 +1,79 @@
+/**
+ * `opice install-skills [--global] [--ref=<branch>]` — install opice's Claude
+ * Code extensions into a project (or `~/.claude` with --global).
+ *
+ *   skills/*  → <target>/.claude/skills/*
+ *   agents/*  → <target>/.claude/agents/*
+ *
+ * Files are pulled from the public GitHub repo (no auth, no publish needed),
+ * so a freshly-onboarded project can `bunx opice install-skills` and pick up
+ * opice-author / opice-plan / opice-batch / opice-reeval + the author agent.
+ *
+ * Project-local is the default so the extensions can be committed and shared
+ * with the team; restart Claude Code afterwards to load them.
+ */
+
+import { promises as fs } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+const REPO = 'contember/opice'
+
+interface TreeEntry {
+	path: string
+	type: string
+}
+
+export async function installSkillsCommand(args: string[]): Promise<number> {
+	const global = args.includes('--global')
+	const ref = args.find((a) => a.startsWith('--ref='))?.slice('--ref='.length) ?? process.env['OPICE_SKILLS_REF'] ?? 'main'
+	const base = path.join(global ? homedir() : process.cwd(), '.claude')
+
+	const headers = { 'user-agent': 'opice-cli', accept: 'application/vnd.github+json' }
+	let tree: TreeEntry[]
+	try {
+		const res = await fetch(`https://api.github.com/repos/${REPO}/git/trees/${ref}?recursive=1`, { headers })
+		if (!res.ok) {
+			console.error(`[opice] could not list ${REPO}@${ref}: ${res.status} ${res.statusText}`)
+			return 1
+		}
+		tree = ((await res.json()) as { tree?: TreeEntry[] }).tree ?? []
+	} catch (err) {
+		console.error(`[opice] request failed: ${(err as Error).message}`)
+		return 1
+	}
+
+	const files = tree.filter(
+		(t) => t.type === 'blob' && (t.path.startsWith('skills/') || (t.path.startsWith('agents/') && t.path.endsWith('.md'))),
+	)
+	if (files.length === 0) {
+		console.error(`[opice] no skills/agents found in ${REPO}@${ref}`)
+		return 1
+	}
+
+	let written = 0
+	for (const file of files) {
+		try {
+			const res = await fetch(`https://raw.githubusercontent.com/${REPO}/${ref}/${file.path}`, {
+				headers: { 'user-agent': 'opice-cli' },
+			})
+			if (!res.ok) {
+				console.error(`[opice] skip ${file.path}: ${res.status}`)
+				continue
+			}
+			const body = Buffer.from(await res.arrayBuffer())
+			const dst = path.join(base, file.path) // file.path is already `skills/…` / `agents/…`
+			await fs.mkdir(path.dirname(dst), { recursive: true })
+			await fs.writeFile(dst, body)
+			written++
+		} catch (err) {
+			console.error(`[opice] skip ${file.path}: ${(err as Error).message}`)
+		}
+	}
+
+	const skillNames = new Set(files.filter((f) => f.path.startsWith('skills/')).map((f) => f.path.split('/')[1]))
+	console.log(`✓ Installed ${written} file(s) into ${base}`)
+	console.log(`  skills: ${[...skillNames].join(', ') || '—'}`)
+	console.log('  Restart Claude Code to load the extensions.')
+	return 0
+}

package/src/commands/test.ts

@@ -0,0 +1,105 @@
+import { spawn } from 'node:child_process'
+import { promises as fs } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { loadConfig } from '../config'
+import { parseOpiceDsn } from '../dsn'
+import { detectGitMeta } from '../git'
+
+const HANDOFF_DIR = path.join(tmpdir(), 'opice-handoffs')
+
+interface Handoff {
+	endpoint: string
+	apiKey: string
+	runId: string
+}
+
+export async function testCommand(args: string[]): Promise<number> {
+	const config = await loadConfig()
+	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
+
+	if (!project) {
+		warn('OPICE_PROJECT not set and no opice.config.json found. Run `opice init` or set the env var.')
+	}
+	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.')
+	}
+
+	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
+		// harness reporter reads, so a bare OPICE_DSN is enough to report.
+		...(apiKey ? { OPICE_API_KEY: apiKey } : {}),
+		...(git.branch ? { OPICE_BRANCH: git.branch } : {}),
+		...(git.commit ? { OPICE_COMMIT: git.commit } : {}),
+	}
+
+	// Always invoke `bun test`; any user-passed args go after.
+	const child = spawn('bun', ['test', ...args], { stdio: 'inherit', env })
+
+	const exitCode = await new Promise<number>((resolve) => {
+		child.on('exit', (code) => resolve(code ?? 1))
+	})
+
+	// 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, process.env['OPICE_READ_TOKEN'])
+
+	return exitCode
+}
+
+async function finalizeHandoffs(childPid: number | undefined, slug: string | undefined, readToken: string | undefined): Promise<void> {
+	let files: string[]
+	try {
+		files = await fs.readdir(HANDOFF_DIR)
+	} catch {
+		return // no handoff dir → no runs reported, nothing to finalize
+	}
+	const matching = childPid ? files.filter((f) => f === `${childPid}.json`) : files
+	for (const file of matching) {
+		const full = path.join(HANDOFF_DIR, file)
+		try {
+			const handoff = JSON.parse(await fs.readFile(full, 'utf-8')) as Handoff
+			await finishRun(handoff)
+			printRunUrl(handoff, slug, readToken)
+		} catch (err) {
+			warn(`Failed to finalize run from ${file}: ${(err as Error).message}`)
+		} finally {
+			await fs.unlink(full).catch(() => {})
+		}
+	}
+}
+
+function printRunUrl(handoff: Handoff, slug: string | undefined, readToken: string | undefined): void {
+	if (!slug) return
+	const query = readToken ? `?token=${readToken}` : ''
+	const url = `${handoff.endpoint}/p/${slug}/r/${handoff.runId}${query}`
+	console.error(`[opice] View run: ${url}`)
+	if (!readToken) {
+		console.error('[opice] (open the dashboard for the tokened read-only link, or set OPICE_READ_TOKEN to embed it here)')
+	}
+}
+
+async function finishRun(handoff: Handoff): Promise<void> {
+	const url = `${handoff.endpoint}/api/v1/runs/${handoff.runId}/finish`
+	const response = await fetch(url, {
+		method: 'POST',
+		headers: { authorization: `Bearer ${handoff.apiKey}` },
+	})
+	if (!response.ok) {
+		throw new Error(`${response.status} ${await response.text()}`)
+	}
+}
+
+function warn(message: string): void {
+	console.error(`[opice] warning: ${message}`)
+}

package/src/commands/users.ts

@@ -0,0 +1,95 @@
+/**
+ * `opice users create <email>` — create a dashboard login.
+ *
+ * Self-service signup is disabled on the platform; this is the sanctioned way
+ * to mint an account. It calls the admin endpoint, so it needs the admin token
+ * (--admin-token or OPICE_ADMIN_TOKEN) and the platform endpoint (--endpoint,
+ * OPICE_ENDPOINT, or opice.config.json). Every account is a full admin.
+ *
+ * If no password is given one is generated and printed once.
+ */
+
+import { loadConfig } from '../config'
+import { parseOpiceDsn } from '../dsn'
+
+interface CreateUserFlags {
+	email?: string
+	password?: string
+	name?: string
+	endpoint?: string
+	adminToken?: string
+}
+
+export async function usersCommand(args: string[]): Promise<number> {
+	const [sub, ...rest] = args
+	if (sub !== 'create') {
+		console.error('Usage: opice users create <email> [--password=...] [--name=...] [--endpoint=URL] [--admin-token=TOKEN]')
+		return 1
+	}
+
+	const flags = parseFlags(rest)
+	if (!flags.email) {
+		console.error('Usage: opice users create <email> [--password=...] [--name=...] [--endpoint=URL] [--admin-token=TOKEN]')
+		return 1
+	}
+
+	const endpoint = flags.endpoint ?? process.env['OPICE_ENDPOINT'] ?? (await loadConfig())?.endpoint ?? parseOpiceDsn(process.env['OPICE_DSN'])?.endpoint
+	if (!endpoint) {
+		console.error('Could not determine the platform endpoint. Pass --endpoint=URL, set OPICE_ENDPOINT, or run from a project with opice.config.json.')
+		return 1
+	}
+
+	const adminToken = flags.adminToken ?? process.env['OPICE_ADMIN_TOKEN']
+	if (!adminToken) {
+		console.error('Missing admin token. Pass --admin-token=TOKEN or set OPICE_ADMIN_TOKEN.')
+		return 1
+	}
+
+	const generated = !flags.password
+	const password = flags.password ?? generatePassword()
+
+	let response: Response
+	try {
+		response = await fetch(`${endpoint.replace(/\/$/, '')}/api/v1/admin/users`, {
+			method: 'POST',
+			headers: { 'content-type': 'application/json', 'x-admin-token': adminToken },
+			body: JSON.stringify({ email: flags.email, password, ...(flags.name ? { name: flags.name } : {}) }),
+		})
+	} catch (err) {
+		console.error(`[opice] request failed: ${(err as Error).message}`)
+		return 1
+	}
+
+	const data = (await response.json().catch(() => null)) as { email?: string; error?: { message?: string } } | null
+	if (!response.ok || !data || data.error) {
+		const message = data?.error?.message ?? `${response.status} ${response.statusText}`
+		console.error(`[opice] could not create user: ${message}`)
+		return 1
+	}
+
+	console.log(`✓ Created user ${data.email ?? flags.email}`)
+	if (generated) {
+		console.log(`  password: ${password}`)
+		console.log('  (shown once — store it in your password manager now)')
+	}
+	return 0
+}
+
+function parseFlags(args: string[]): CreateUserFlags {
+	const flags: CreateUserFlags = {}
+	for (const arg of args) {
+		if (arg.startsWith('--password=')) flags.password = arg.slice('--password='.length)
+		else if (arg.startsWith('--name=')) flags.name = arg.slice('--name='.length)
+		else if (arg.startsWith('--endpoint=')) flags.endpoint = arg.slice('--endpoint='.length)
+		else if (arg.startsWith('--admin-token=')) flags.adminToken = arg.slice('--admin-token='.length)
+		else if (!arg.startsWith('--') && !flags.email) flags.email = arg
+	}
+	return flags
+}
+
+/** A 20-char base64url password — comfortably over the 10-char server minimum. */
+function generatePassword(): string {
+	const bytes = new Uint8Array(15)
+	crypto.getRandomValues(bytes)
+	return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}

package/src/config.ts

@@ -0,0 +1,32 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+export interface OpiceConfig {
+	project: string
+	endpoint: string
+}
+
+const CONFIG_NAME = 'opice.config.json'
+
+export async function loadConfig(cwd: string = process.cwd()): Promise<OpiceConfig | null> {
+	// Walk up from cwd until we find opice.config.json or hit the root.
+	let dir = path.resolve(cwd)
+	while (true) {
+		const candidate = path.join(dir, CONFIG_NAME)
+		try {
+			const text = await fs.readFile(candidate, 'utf-8')
+			return JSON.parse(text) as OpiceConfig
+		} catch {
+			// continue up
+		}
+		const parent = path.dirname(dir)
+		if (parent === dir) return null
+		dir = parent
+	}
+}
+
+export async function writeConfig(cwd: string, config: OpiceConfig): Promise<string> {
+	const target = path.join(cwd, CONFIG_NAME)
+	await fs.writeFile(target, JSON.stringify(config, null, '\t') + '\n', 'utf-8')
+	return target
+}

package/src/dsn.ts

@@ -0,0 +1,32 @@
+/**
+ * An opice DSN packs everything a project needs to report into one string:
+ *
+ *   OPICE_DSN=https://<apiKey>@<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`.
+ *
+ * Kept in sync with `@opice/harness`'s copy; duplicated to avoid a CLI→harness
+ * dependency.
+ */
+export interface OpiceDsn {
+	apiKey: string
+	endpoint: string
+	project: string
+}
+
+export function parseOpiceDsn(raw: string | undefined | null): OpiceDsn | null {
+	if (!raw) return null
+	let url: URL
+	try {
+		url = new URL(raw)
+	} catch {
+		return null
+	}
+	const apiKey = decodeURIComponent(url.username)
+	const project = url.pathname.replace(/^\/+/, '').split('/')[0] ?? ''
+	if (!apiKey || !project) return null
+	return { apiKey, endpoint: `${url.protocol}//${url.host}`, project }
+}

package/src/git.ts

@@ -0,0 +1,29 @@
+import { execSync } from 'node:child_process'
+
+/**
+ * Best-effort git metadata for the current working tree. Returns the values
+ * configured in opice runs (branch, commit). Falls back to env vars commonly
+ * set by CI (GITHUB_REF_NAME, GITHUB_SHA) when not in a git checkout.
+ */
+export function detectGitMeta(): { branch?: string; commit?: string } {
+	const fromEnv = {
+		branch: process.env['OPICE_BRANCH'] ?? process.env['GITHUB_REF_NAME'],
+		commit: process.env['OPICE_COMMIT'] ?? process.env['GITHUB_SHA'],
+	}
+	if (fromEnv.branch && fromEnv.commit) return fromEnv
+
+	try {
+		const branch = run('git rev-parse --abbrev-ref HEAD')
+		const commit = run('git rev-parse HEAD')
+		return {
+			branch: fromEnv.branch ?? branch,
+			commit: fromEnv.commit ?? commit,
+		}
+	} catch {
+		return fromEnv
+	}
+}
+
+function run(cmd: string): string {
+	return execSync(cmd, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+}