@octane-xplat/mcp 0.1.0 → 0.16.0

package/types/contracts/identity.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Project identity contract — what the server detects and reports about the
+ * developer's workspace during setup, and the shape of the project-status
+ * report every later package (docs, code, runtime) plugs into.
+ */
+
+export const PLATFORMS: readonly Platform[]
+
+/** The six release-boundary targets. `web` means Chromium acceptance checks. */
+export type Platform = 'web' | 'ios' | 'android' | 'macos' | 'linux' | 'windows'
+
+/** A detected application inside the selected workspace. */
+export interface AppRef {
+	/** Stable identity for selection and binding: workspace-relative root path ('.' for the root app). */
+	id: string
+	/** package.json name, falling back to the directory basename. */
+	name: string
+	/** Absolute path. */
+	root: string
+	/** Path relative to the workspace root. */
+	relativeRoot: string
+	/**
+	 * `consumer-app` — a deployable Octane Xplat application (the primary setup path).
+	 * `framework-package` — a package inside the octane-xplat framework repository
+	 * (identified separately, never silently treated as the consumer app).
+	 */
+	kind: 'consumer-app' | 'framework-package'
+	/** Platforms this app declares (from its config and dependencies). */
+	platforms: Platform[]
+}
+
+/** Where a package version came from. `installed` is the only version that binds docs. */
+export type VersionSource = 'installed' | 'workspace' | 'lockfile' | 'unresolved'
+
+export interface PackageVersion {
+	/** e.g. `@octane-xplat/ui`. */
+	name: string
+	version: string | null
+	source: VersionSource
+	/** The declared range in the app's manifest, when it differs from the resolved version. */
+	declared?: string
+}
+
+export interface FrameworkBinding {
+	packages: PackageVersion[]
+	/**
+	 * `installed` — resolved from the app's actual node_modules (binds documentation).
+	 * `provisional` — lockfile/declared only; the real install could not be verified.
+	 * `unresolved` — no version information at all.
+	 */
+	status: 'installed' | 'provisional' | 'unresolved'
+	/** Set when the lockfile and the actual installation disagree; installation wins. */
+	discrepancy?: string
+}
+
+export interface GuidanceSource {
+	kind: 'agents-md' | 'claude-md' | 'devin' | 'framework' | 'other'
+	/** Workspace-relative path. */
+	path: string
+}
+
+/** Project-level guidance the agent should read; never mixed into generic docs results. */
+export interface GuidanceStatus {
+	sources: GuidanceSource[]
+}
+
+/** Optional-subsystem readiness. `not_provided` = no provider registered yet. */
+export type SubsystemState = 'ready' | 'preparing' | 'stale' | 'unavailable' | 'not_provided'
+
+export interface DocsStatus {
+	state: SubsystemState
+	/** e.g. which version binding is active, or why docs are unavailable. */
+	detail?: string
+}
+
+export interface CodeIndexStatus {
+	state: SubsystemState
+	detail?: string
+	/** Human-readable freshness marker (index revision vs working tree). */
+	freshness?: string
+}
+
+export type PrerequisiteStatus = 'satisfied' | 'missing' | 'unknown'
+
+export interface RuntimePrerequisite {
+	/** Stable id: `node`, `git`, `pnpm`, `xcode`, `adb`, `nativescript-cli`, `chromium`, … */
+	id: string
+	name: string
+	status: PrerequisiteStatus
+	/** e.g. the found version, or where it was looked for. */
+	detail?: string
+	/** The smallest corrective action when missing/unknown. */
+	remedy?: string
+	/** Platforms this prerequisite gates; absent = server-wide. */
+	platforms?: Platform[]
+}
+
+/** The workspace as a whole. */
+export type WorkspaceKind =
+	/** A consumer application workspace (single- or multi-app monorepo). */
+	| 'consumer'
+	/** The octane-xplat framework repository itself — framework sources are a separate corpus. */
+	| 'framework-repo'
+	/** No Octane Xplat app detected. */
+	| 'empty'
+
+export interface WorkspaceInfo {
+	root: string
+	kind: WorkspaceKind
+}
+
+/**
+ * App selection state. `ambiguous` is a first-class state: the server never
+ * silently picks among multiple apps — the developer (via the agent) must choose.
+ */
+export type AppSelection =
+	| { state: 'bound'; app: AppRef; reason: 'explicit' | 'sole-app' | 'configured' | 'preference' }
+	| { state: 'ambiguous'; candidates: AppRef[] }
+	| { state: 'none'; reason: 'no-apps' | 'workspace-not-found' }
+
+export interface ProjectIdentity {
+	workspace: WorkspaceInfo
+	apps: AppRef[]
+	selection: AppSelection
+	/** Framework versions for the bound app (null while selection is ambiguous/none). */
+	framework: FrameworkBinding | null
+}

package/types/contracts/index.d.ts

@@ -0,0 +1,11 @@
+export * from './errors'
+export * from './identity'
+export * from './capabilities'
+export * from './policy'
+export * from './sessions'
+export * from './evidence'
+export * from './boundaries'
+export * from './status'
+export * from './code'
+export * from './actions'
+export * from './inspection'

package/types/contracts/inspection.d.ts

@@ -0,0 +1,45 @@
+import type { EvidenceRecord } from './evidence'
+
+/** Qualified scope of Chromium inspection; never a universal component tree. */
+export const CHROMIUM_INSPECTION_COVERAGE: string
+
+/** Select exactly one named DOM host. Duplicate names fail rather than choosing the first. */
+export interface StableControl {
+	kind: 'id' | 'testID'
+	name: string
+}
+
+export interface InspectedHost {
+	id: string | null
+	testID: string | null
+	tag: string
+	role: string | null
+	/** Bounded to 500 characters; password and data-xplat-private hosts are redacted. */
+	text: string
+	value: string | null
+	checked: boolean | null
+	disabled: boolean
+	hidden: boolean
+	sensitive: boolean
+	focused: boolean
+	hitTarget: boolean
+	/** Main-document CSS pixels, relative to the viewport. */
+	frame: { x: number; y: number; width: number; height: number }
+}
+
+/** Returned by xplat_inspect; documentId must accompany subsequent interactions. */
+export interface HostInspection {
+	documentId: string
+	controls: InspectedHost[]
+	coverage: string
+	limitations: string[]
+	total: number
+	nextOffset: number | null
+	evidence: EvidenceRecord
+}
+
+/** Input submission proves delivery only; observe and assert the intended state separately. */
+export interface HostInteraction extends HostInspection {
+	inputSent: true
+	assertion: string
+}

package/types/contracts/policy.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Permission/policy contract. Workspace scope and ordinary runtime actions
+ * reuse the existing task authorization — policy is established once, not
+ * re-requested per tool call. Grants are scoped, revocable, optionally
+ * expiring, and checked at action time. `visual-capture` is never part of
+ * any baseline: the screenshot capability can exist while every actual
+ * capture still requires explicit per-task developer approval.
+ */
+
+import type { ContractError } from './errors'
+
+export const PERMISSION_SCOPES: readonly PermissionScope[]
+
+export type PermissionScope =
+	/** Read the selected workspace: manifests, config, source inventory. */
+	| 'workspace'
+	/** Build, launch, attach, and interact with development sessions. */
+	| 'runtime-actions'
+	/** Screenshot capture and any visual inspection of captured pixels. Never granted by task authorization alone. */
+	| 'visual-capture'
+	/** Persist evidence artifacts beyond the MCP session. */
+	| 'evidence-retain'
+	/** Effects outside the app itself (external services, destructive resets). Never implied by runtime-actions. */
+	| 'external-effects'
+
+export type GrantSource =
+	/** The developer authorized this task; covers workspace + runtime-actions only. */
+	| 'task-authorization'
+	/** An explicit developer approval for this task (e.g. via client elicitation). */
+	| 'developer'
+	/** A server startup flag/environment setting the developer configured. */
+	| 'server-config'
+
+export type GrantState = 'granted' | 'denied' | 'required'
+
+export interface PermissionGrant {
+	scope: PermissionScope
+	state: GrantState
+	source?: GrantSource
+	grantedAt?: string
+	/** ISO timestamp after which the grant no longer applies; absent = session-bound. */
+	expiresAt?: string
+	/** False only for server-internal baseline entries; everything the developer grants is revocable. */
+	revocable: boolean
+	note?: string
+}
+
+export type RequireResult =
+	| { granted: true; grant: PermissionGrant }
+	| { granted: false; error: ContractError }
+
+/**
+ * The channel that asks the developer for a grant — wired to the client's
+ * elicitation support when available. Returns the resulting state.
+ */
+export type GrantElicitor = (
+	scope: PermissionScope,
+	reason: string,
+) => Promise<'granted' | 'denied'> | 'granted' | 'denied'
+
+export interface PolicyStoreOptions {
+	/** The developer authorized this task — grants workspace + runtime-actions for the session. */
+	taskAuthorization?: boolean
+	/** Extra grants from server configuration (env/flags), e.g. a pre-approved visual-capture. */
+	grants?: PermissionGrant[]
+	/** Optional elicitation channel used by `requestGrant`. */
+	elicit?: GrantElicitor
+}
+
+export interface PolicyStore {
+	/** Synchronous check used at action time. Expired grants are denied. */
+	require(scope: PermissionScope): RequireResult
+	/**
+	 * Resolve a grant, asking the developer through the elicitation channel when
+	 * one exists. Without a channel, returns `required` state plus the recovery
+	 * text telling the developer how to grant it.
+	 */
+	requestGrant(scope: PermissionScope, reason: string): Promise<RequireResult>
+	grant(scope: PermissionScope, grant?: Partial<PermissionGrant>): PermissionGrant
+	revoke(scope: PermissionScope): boolean
+	list(): PermissionGrant[]
+	/** Late-bind the elicitation channel (it needs a connected client). */
+	setElicitor(elicit: GrantElicitor): void
+}
+
+export declare function createPolicyStore(options?: PolicyStoreOptions): PolicyStore

package/types/contracts/sessions.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Session, job, and ownership contract.
+ *
+ * A session binds one app to one target. Sessions are either `owned` (this
+ * server started them — ending releases their resources) or `attached`
+ * (a development session the user already had running — ending detaches and
+ * preserves it). Restarting always establishes a new session identity; tools
+ * refuse operations against stopped or disconnected sessions.
+ *
+ * Jobs are bounded units of work (build, launch, dev-action, …) whose status
+ * is queryable without holding a tool call open. Repeating a request with the
+ * same `requestKey` returns the live job instead of duplicating it.
+ * Cancellation is cooperative: `cancelling` and `cancelled` are distinct
+ * states, and cancelling a job only signals that job's own operation — it
+ * must never kill an unrelated app.
+ */
+
+import type { ContractError } from './errors'
+import type { Platform } from './identity'
+
+export const SESSION_STATES: readonly SessionState[]
+export const JOB_STATES: readonly JobState[]
+export const JOB_TERMINAL_STATES: readonly JobState[]
+
+export type SessionState =
+	/** Bound but not yet ready for observation/interaction. */
+	| 'starting'
+	/** Ready — inspection, logs, and authorized interactions may proceed. */
+	| 'ready'
+	/** Lost contact; last-known data is historical evidence, never current state. */
+	| 'disconnected'
+	/** Ended — identity is stale; a new run is a new sessionId. */
+	| 'stopped'
+
+export type SessionOwnership =
+	/** Started by this server; end releases owned resources. */
+	| 'owned'
+	/** Pre-existing user session; end detaches and preserves it. */
+	| 'attached'
+
+/** Build/source identity attached to observations so a new install is never mistaken for the running process. */
+export interface BuildIdentity {
+	buildId?: string
+	revision?: string
+	label?: string
+}
+
+export interface SessionBinding {
+	sessionId: string
+	appId: string
+	platform: Platform
+	targetId: string
+	ownership: SessionOwnership
+	state: SessionState
+	createdAt: string
+	/** `fresh` = new process; `warm` = iteration that retained process/module/OS state. */
+	processKind: 'fresh' | 'warm' | null
+	buildIdentity?: BuildIdentity
+	detail?: string
+}
+
+export interface EndSessionResult {
+	sessionId: string
+	ended: boolean
+	/** Owned resources released (processes, ports, temp dirs) — reported by the adapter. */
+	released?: string[]
+	/** What was deliberately left running — e.g. an attached user-owned session. */
+	preserved?: string[]
+}
+
+export type JobState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelling' | 'cancelled'
+
+export interface JobProgress {
+	phase?: string
+	percent?: number
+	message?: string
+}
+
+export interface Job {
+	jobId: string
+	/** e.g. `build`, `launch`, `attach`, `dev-action`. */
+	kind: string
+	sessionId?: string
+	/** Idempotence key supplied by the caller or adapter. */
+	requestKey?: string
+	state: JobState
+	progress?: JobProgress
+	result?: unknown
+	error?: ContractError
+	createdAt: string
+	finishedAt?: string
+}
+
+/** Adapter-provided work for a job. Receives the cooperative-cancel signal. */
+export type JobRunner = (
+	signal: AbortSignal,
+	report: (progress: JobProgress) => void,
+) => Promise<unknown>
+
+export interface StartJobOptions {
+	kind: string
+	sessionId?: string
+	requestKey?: string
+	run?: JobRunner
+}
+
+export interface StartJobResult {
+	job: Job
+	/** True when an identical live job already existed and was returned instead of starting a duplicate. */
+	deduplicated: boolean
+}
+
+export interface SessionRegistry {
+	/** Start a server-owned session in `starting` state. `cleanup` runs on end/shutdown and must only release resources this session created. */
+	bindOwned(input: {
+		appId: string
+		platform: Platform
+		targetId: string
+		cleanup?: () => Promise<{ released?: string[] } | void> | { released?: string[] } | void
+		detail?: string
+	}): SessionBinding
+	/** Bind an existing user-owned development session — never restarted or terminated by this server. */
+	attach(input: {
+		appId: string
+		platform: Platform
+		targetId: string
+		processKind?: 'fresh' | 'warm'
+		buildIdentity?: BuildIdentity
+		detail?: string
+	}): SessionBinding
+	get(sessionId: string): SessionBinding | null
+	/** The binding if usable, else a ContractError: `stale_identity` (stopped) or `disconnected_runtime`. */
+	requireUsable(
+		sessionId: string,
+	): { usable: true; session: SessionBinding } | { usable: false; error: ContractError }
+	markReady(
+		sessionId: string,
+		meta?: { processKind?: 'fresh' | 'warm'; buildIdentity?: BuildIdentity },
+	): SessionBinding | null
+	markDisconnected(sessionId: string, detail?: string): SessionBinding | null
+	end(sessionId: string): Promise<EndSessionResult>
+	/** End every owned session and detach attached ones. */
+	shutdown(): Promise<EndSessionResult[]>
+	list(): SessionBinding[]
+}
+
+export interface JobRegistry {
+	start(options: StartJobOptions): StartJobResult
+	status(jobId: string): Job | null
+	setProgress(jobId: string, progress: JobProgress): Job | null
+	succeed(jobId: string, result?: unknown): Job | null
+	fail(jobId: string, error: ContractError): Job | null
+	/** Cooperative cancellation; returns the job's resulting state. */
+	cancel(jobId: string): Job | null
+	/** Live and finished jobs (finished history is bounded). */
+	list(): Job[]
+}
+
+export declare function createSessionRegistry(): SessionRegistry
+export declare function createJobRegistry(options?: { historyLimit?: number }): JobRegistry

package/types/contracts/status.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The project-status report — the single externally observable shape returned
+ * by `xplat_project_status` at setup time. Later packages fill their own
+ * slots through registered providers; absent providers read as
+ * `not_provided`, never as healthy or silently absent.
+ */
+
+import type {
+	CodeIndexStatus,
+	DocsStatus,
+	GuidanceStatus,
+	ProjectIdentity,
+	RuntimePrerequisite,
+} from './identity'
+
+import type { PlatformCapabilityMatrix } from './capabilities'
+import type { PermissionGrant } from './policy'
+
+export interface ServerInfo {
+	name: string
+	version: string
+}
+
+export interface ProjectStatusReport {
+	server: ServerInfo
+	identity: ProjectIdentity
+	guidance: GuidanceStatus
+	docs: DocsStatus
+	codeIndex: CodeIndexStatus
+	/** Prerequisites relevant to the detected apps' declared platforms. */
+	prerequisites: RuntimePrerequisite[]
+	/** Matrix for the workspace's declared platforms. */
+	capabilities: PlatformCapabilityMatrix[]
+	/** Current permission grants and their states. */
+	permissions: PermissionGrant[]
+	/** What this product deliberately does not do. */
+	boundaries: readonly string[]
+	/** Ordered next steps for the agent, tailored to the report's actual state. */
+	nextSteps: string[]
+}