overlord-cli 0.2607121101.0 → 0.2607141312.0

package/README.md

@@ -130,9 +130,12 @@ Both the desktop app and the CLI authenticate to `/api/*` with a bearer token:
   sign-in on the **local** backend. Stored in `~/.ovld/auth.json` for the CLI
   and in the desktop shell's encrypted settings for each backend profile.
 - **USER_TOKEN** (`out_…`) — long-lived token from Settings → Tokens. Works for
-  headless/CI use via `OVERLORD_USER_TOKEN` or `ovld auth login --token`. On
-  cloud backends, interactive email/password login creates and stores a full
-  `USER_TOKEN` automatically so runner/protocol CLI surfaces can authenticate.
+  headless/CI use via `OVERLORD_USER_TOKEN` or `ovld auth login --token`.
+  Interactive email/password login creates and stores a full 90-day `USER_TOKEN`
+  automatically **in both local and cloud modes**, so runner/protocol CLI
+  surfaces authenticate with a consistent, long-lived credential. (Local logins
+  previously stored the raw 7-day Better Auth session token, which is why they
+  expired far sooner than cloud logins.)
 
 For the **local** backend, desktop and CLI share `~/.ovld/auth.json`:
 
@@ -146,13 +149,18 @@ For the **local** backend, desktop and CLI share `~/.ovld/auth.json`:
 desktop app updates `~/.ovld/overlord.toml` with the new `backend_url`, but it
 does **not** update CLI auth. After switching backends in either surface, run
 `ovld auth status` to confirm the CLI is pointed at the same URL and still
-logged in. If `credentialSource` is `stored_mismatch` or `loggedIn` is false, run
-`ovld config set cloud <url>` (if needed) and `ovld auth login`. Email/password
-login on a cloud backend uses the session only once to create a 90-day full
-`USER_TOKEN`, then stores that token in `auth.json`.
-
-When a stored CLI credential is rejected with HTTP 401, `ovld` clears
-`auth.json` and tells you to run `ovld auth login` again.
+logged in. `auth status` also reports `expires_at` (with days remaining) when the
+stored credential is a minted `USER_TOKEN`, so you can see a credential's
+lifetime instead of just a logged-in boolean. If `credentialSource` is
+`stored_mismatch` or `loggedIn` is false, run `ovld config set cloud <url>` (if
+needed) and `ovld auth login`. Email/password login uses the session only once to
+create a 90-day full `USER_TOKEN`, then stores that token in `auth.json`.
+
+When a stored CLI credential is rejected with HTTP 401, `ovld` leaves `auth.json`
+in place (a 401 can be transient) and tells you to run `ovld auth login` again.
+To reconcile a broken login in one step, run `ovld auth repair`: it validates the
+current credential, reports "healthy" when nothing is wrong, and otherwise clears
+the stale stored credential and walks you through a fresh login.
 
 ### Headless / container setup
 

package/dist/contract/conformance-manifest.schema.yaml

@@ -0,0 +1,328 @@
+# Overlord Conformance Manifest Schema
+# JSON Schema (YAML format) — every component that ships against Overlord
+# must provide a conformance-manifest.yaml in its root that validates against this schema.
+#
+# Validate with: ovld contract check <manifest-file>
+#
+# Example manifests live in contract/examples/
+
+"$schema": "https://json-schema.org/draft/2020-12/schema"
+"$id": "openoverllord/conformance-manifest/v1"
+title: "Overlord Conformance Manifest"
+description: >
+  Every connector, extension, database adapter, auth provider, REST module, desktop shell, or MCP server that ships
+  against Overlord must provide a conformance-manifest.yaml at its root.
+  The manifest declares which contract version the component was validated against,
+  what kind of component it is, and which extension points and vocabulary values it uses.
+
+type: object
+required:
+  - contractVersion
+  - componentType
+  - componentKey
+  - label
+
+additionalProperties: false
+
+properties:
+
+  contractVersion:
+    type: string
+    description: "The Overlord contract version this component was validated against (e.g. '0')"
+    examples:
+      - "0"
+
+  componentType:
+    type: string
+    enum:
+      - connector
+      - extension
+      - database-adapter
+      - auth-provider
+      - rest-module
+      - rest-consumer
+      - desktop-shell
+      - mcp-server
+    description: "The kind of component being shipped"
+
+  componentKey:
+    type: string
+    pattern: "^[a-z][a-z0-9_-]*$"
+    description: "Stable lowercase identifier for this component (e.g. claude, my-custom-harness)"
+
+  label:
+    type: string
+    description: "Human-readable display name"
+
+  description:
+    type: string
+    description: "Optional description of what this component does"
+
+  # ── Connector-specific fields ────────────────────────────────────────────────
+
+  connector:
+    type: object
+    description: "Required when componentType is 'connector'"
+    required:
+      - agentIdentifier
+      - capabilities
+    additionalProperties: false
+    properties:
+      agentIdentifier:
+        type: string
+        description: "The stable agent identifier used by this connector (e.g. claude, codex, cursor)"
+      capabilities:
+        type: array
+        description: "Capability flags this connector supports — must be from the approvedConnectorCapabilities list in contract/extension-points.yaml"
+        items:
+          type: string
+          enum:
+            - followUpHook
+            - permissionHook
+            - stopHook
+            - nativeResume
+            - modelFlag
+            - effortFlag
+            - contextFilePrompt
+            - permissionRules
+            - slashCommands
+        uniqueItems: true
+      hookTypes:
+        type: array
+        description: "Hook types this connector uses — must be from approvedHookTypes in contract/extension-points.yaml"
+        items:
+          type: string
+          enum:
+            - UserPromptSubmit
+            - PermissionRequest
+            - Stop
+        uniqueItems: true
+      managedFiles:
+        type: array
+        description: "Paths of files this connector installs and manages (relative to install location)"
+        items:
+          type: string
+      installPath:
+        type: string
+        description: "Default install location for connector files (e.g. ~/.codex/plugins/overlord)"
+
+  # ── Extension-specific fields ────────────────────────────────────────────────
+
+  extension:
+    type: object
+    description: "Required when componentType is 'extension'"
+    additionalProperties: false
+    properties:
+      tablePrefix:
+        type: string
+        pattern: "^ext_[a-z][a-z0-9_]*_$"
+        description: "Database table prefix — must follow ext_<name>_ pattern"
+        examples:
+          - "ext_myfeature_"
+      migrationComponent:
+        type: string
+        pattern: "^ext:[a-z][a-z0-9_-]*$"
+        description: "schema_migrations.component value — must follow ext:<name> pattern"
+        examples:
+          - "ext:myfeature"
+      metadataKeyPrefix:
+        type: string
+        description: "Namespace prefix for JSON metadata keys stored in core table columns (e.g. com.example or mypackage)"
+      usesExtensionPoints:
+        type: array
+        description: "Extension points from contract/extension-points.yaml that this extension uses"
+        items:
+          type: string
+          enum:
+            - database-extension
+            - custom-harness
+            - open-vocabulary-value
+        uniqueItems: true
+
+  # ── Database adapter-specific fields ─────────────────────────────────────────
+
+  databaseAdapter:
+    type: object
+    description: "Required when componentType is 'database-adapter'"
+    required:
+      - adapterKey
+      - schemaContractVersion
+    additionalProperties: false
+    properties:
+      adapterKey:
+        type: string
+        description: "Adapter identifier (e.g. sqlite, postgres)"
+        examples:
+          - sqlite
+          - postgres
+      schemaContractVersion:
+        type: string
+        description: "Database schema contract version this adapter implements (from 09-database-schema-contract.md)"
+      conformanceTestStatus:
+        type: string
+        enum:
+          - passing
+          - partial
+          - pending
+        description: "Current status of adapter conformance test suite"
+      conformanceTestPath:
+        type: string
+        description: "Path to adapter conformance test results or test suite"
+
+  # ── Auth provider-specific fields ────────────────────────────────────────────
+
+  authProvider:
+    type: object
+    description: "Required when componentType is 'auth-provider'"
+    additionalProperties: false
+    properties:
+      authMechanisms:
+        type: array
+        items:
+          type: string
+        description: "Auth mechanisms this provider supports (e.g. user-token, oauth, passkey)"
+        examples:
+          - - user-token
+          - - oauth
+          - - passkey
+      preservesAuditAttribution:
+        type: boolean
+        description: "Declares that this provider writes actor_workspace_user_id and actor_token_id to audit_log correctly"
+      preservesTokenHashRules:
+        type: boolean
+        description: "Declares that raw token secrets are never persisted — hash and prefix only"
+
+  # ── REST module-specific fields ───────────────────────────────────────────────
+
+  restModule:
+    type: object
+    description: "Required when componentType is 'rest-module'"
+    required:
+      - endpointPrefix
+    additionalProperties: false
+    properties:
+      endpointPrefix:
+        type: string
+        pattern: "^/ext/[a-z][a-z0-9/_-]*$"
+        description: "Namespaced URL prefix for all endpoints this module adds — must start with /ext/<name>/"
+        examples:
+          - "/ext/my-integration"
+      usesServiceLayer:
+        type: boolean
+        description: "Declares that this module uses the service layer for database access (no direct table writes)"
+
+  # ── REST consumer-specific fields ─────────────────────────────────────────────
+
+  restConsumer:
+    type: object
+    description: "Required when componentType is 'rest-consumer'"
+    required:
+      - authMechanisms
+      - vendoredContractPath
+      - endpoints
+      - exportedTypes
+    additionalProperties: false
+    properties:
+      authMechanisms:
+        type: array
+        description: "Auth mechanisms this client uses against the REST surface"
+        items:
+          type: string
+          enum:
+            - bearer-token
+            - active-workspace-header
+            - better-auth-email
+        uniqueItems: true
+      vendoredContractPath:
+        type: string
+        description: "Repo-relative path to the vendored @overlord/contract subset"
+        examples:
+          - src/lib/contract.ts
+      upstreamContractRef:
+        type: string
+        description: "Path to the canonical contract source inside the OpenOverlord repo"
+        examples:
+          - packages/contract/src/index.ts
+      endpoints:
+        type: array
+        description: "REST endpoints this client calls"
+        items:
+          type: object
+          required:
+            - method
+            - path
+          additionalProperties: false
+          properties:
+            method:
+              type: string
+              enum:
+                - GET
+                - POST
+                - PATCH
+                - PUT
+                - DELETE
+            path:
+              type: string
+              description: "Route template, e.g. /api/missions/:id"
+            responseType:
+              type: string
+            requestBodyType:
+              type: string
+      exportedTypes:
+        type: array
+        description: "DTO/type names vendored from @overlord/contract"
+        items:
+          type: string
+
+  # ── Desktop shell-specific fields ─────────────────────────────────────────────
+
+  desktopShell:
+    type: object
+    description: "Required when componentType is 'desktop-shell'"
+    additionalProperties: false
+    properties:
+      wrapsModule:
+        type: string
+        description: "The component whose web surface this shell wraps (e.g. webapp/rest)"
+      supervisedProcesses:
+        type: array
+        description: "CLI/server processes this shell launches and supervises"
+        items:
+          type: string
+      bridgeNamespace:
+        type: string
+        description: "The contextBridge global exposed to the renderer (e.g. window.overlord)"
+      packagingTargets:
+        type: array
+        description: "Distribution artifacts this shell can produce (e.g. dmg, zip, AppImage, deb)"
+        items:
+          type: string
+
+  # ── Shared: vocabulary extensions ────────────────────────────────────────────
+
+  vocabularyExtensions:
+    type: array
+    description: "Open vocabulary values this component adds — must be namespaced (reverse-DNS or package-style)"
+    items:
+      type: object
+      required:
+        - vocabulary
+        - value
+      additionalProperties: false
+      properties:
+        vocabulary:
+          type: string
+          description: "The open vocabulary column being extended (e.g. artifacts.type)"
+          examples:
+            - artifacts.type
+            - mission_events.source
+            - entity_changes.entity_type
+        value:
+          type: string
+          description: "The namespaced value being added (e.g. com.example.my-artifact-type)"
+          examples:
+            - "com.example.custom-artifact"
+            - "mypackage:review-event"
+        description:
+          type: string
+          description: "Optional human description of what this vocabulary value represents"