SteamFramelyHomebrew--framely/docs/plugin-relationships.md

Dependencies and conflicts

简体中文

{
  "dependencies": {
    "example.shared-api": "^1.0.0",
    "example.camera-api": {"version": ">=1.2.0 <2.0.0", "source": "https://example.org/plugins/catalog.json"}
  },
  "optionalDependencies": {"example.notifications": "^1.0.0"},
  "conflicts": {"example.other-camera": "*"},
  "exclusiveResources": ["steamvr.passthrough-color"]
}

All four fields are optional. Relationship-declaring plugins and matched dependency/conflict targets use valid SemVer. Ranges support exact versions, ^, ~, * and comma/space comparison conjunctions. 1.2.0 is exact; >=1.2.0 <2.0.0 requires both. || is unsupported. Self-dependencies, duplicate required/optional entries, contradictory conflicts and repeated exclusive resources are rejected.

source is an HTTPS catalog URL, not a subscription or package. Compatible installed versions/sources are reused first. Without explicit source, the originating catalog is preferred; otherwise choose explicitly. An unavailable explicit source is not silently replaced. New explicit sources join the confirmation plan; disabled sources need enabling first. Removing a source retains installed origin URLs for matching.

Local packages with no default source require selecting missing dependency sources:

framely install plugin.framely --source my-source --approve
framely install plugin.framely --dependency-source example.shared-api=https://example.org/catalog.json --approve

Dependency-source flags may repeat, cannot override explicit Manifest sources, and use the UI's resolver. Add --approve-run-as only after reviewing an identity change.

The main catalog contains one recommended entry per ID, with history in relative plugins/<ID>/versions.json. Users may select old versions or reinstall. ID/version/hash/relations are rechecked. Resolution reuses installed matches, otherwise the first matching source entry. Incompatible constraints, cycles or missing required dependencies stop installation. Missing optional dependencies neither prevent installation nor install automatically.

Plans disclose packages, versions, sources, users, added sources, dependency enabling and conflict disabling. Confirmed operations use the same verified bytes; changed device/source state requires another inspection. Plans allow at most 32 plugins without a total package/expanded-size cap. Download/verify first, then install sequentially and check reverse dependencies.

Persistent transaction logs restore links, origins/enabled state, undo newly added packages and attempt to restart previous backends on failure. Startup recovers interrupted transactions. Data remains; file rollback cannot undo migrations or hardware effects, so make them repeatable and recoverable.

Enabling confirms required dependencies and conflicting plugins to disable. Either side's conflict declaration prevents simultaneous enabling, not installation. Matching exclusive resources work likewise. Disabling/removing a base plugin requires confirming dependent disabling; dependents are not automatically removed.

Backends start in dependency order after base onStart succeeds; absent hooks use process startup. Stops reverse that order. Crashed bases pause running dependents in a waiting state without counting dependent failures, then resume them after recovery. Disabled/non-restarting bases need user action.

import {framely, useDependencies} from '@framely/sdk';
const states = await framely.dependencies();
// In React: const {items, error} = useDependencies();

Only declared required/optional dependencies are returned, with version/enabling/range/availability/runtime state. Changes emit dependencies.changed. No cross-plugin backend calls or extra privileges are granted. Conflicts/resources depend on author declarations, not arbitrary file/device detection.

There is no manual plugin rollback API; old-version installation uses the normal plan and onUpdate. Transaction recovery is failure handling, not a version picker. Keep same-ID/version content immutable.