@sharpee/ide-protocol 1.0.8 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# @sharpee/ide-protocol
|
|
2
|
+
|
|
3
|
+
Wire types for the Sharpee IDE project-introspection manifest (ADR-184).
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @sharpee/ide-protocol
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
The single source of truth for the manifest contract between the platform's introspection emitters and the Sharpee IDE:
|
|
14
|
+
|
|
15
|
+
- **Types only** - No runtime dependencies and no runtime-specific types (`Buffer`, `fs`, DOM), so both the Node `--introspect` CLI emitter and the browser Play-panel bridge import it cleanly (DEVARCH 8b).
|
|
16
|
+
- **`ProjectManifest`** - A flat list of introspected entities plus a build-status header; the IDE buckets entities into categories client-side.
|
|
17
|
+
- **`EntityNode` / `EntityCategory`** - One world entity per node, with `id`, `displayName`, `category` (`room` | `object` | `npc` | `region`), a `TraitSummary`, and an optional `SourceRef`.
|
|
18
|
+
- **`SourceRef`** - Resolved `file:line` of the entity's `createEntity(...)` site (`exact` or `scope` resolution).
|
|
19
|
+
- **`SCHEMA_VERSION`** plus type guards (`isProjectManifest`, `isEntityNode`, …) for validating manifests on receipt.
|
|
20
|
+
|
|
21
|
+
## Usage
|
|
22
|
+
|
|
23
|
+
The platform emits a `ProjectManifest` by running a story's world construction and projecting the resulting entities. The IDE consumes it to render a Sharpee-aware project tree. The Swift IDE mirrors these shapes as `Codable` structs.
|
|
24
|
+
|
|
25
|
+
```typescript
|
|
26
|
+
import {
|
|
27
|
+
isProjectManifest,
|
|
28
|
+
SCHEMA_VERSION,
|
|
29
|
+
type ProjectManifest,
|
|
30
|
+
} from '@sharpee/ide-protocol';
|
|
31
|
+
|
|
32
|
+
function handleManifest(payload: unknown): ProjectManifest {
|
|
33
|
+
if (!isProjectManifest(payload)) {
|
|
34
|
+
throw new Error('Not a Sharpee project manifest');
|
|
35
|
+
}
|
|
36
|
+
if (payload.schemaVersion !== SCHEMA_VERSION) {
|
|
37
|
+
throw new Error(`Unsupported manifest schema ${payload.schemaVersion}`);
|
|
38
|
+
}
|
|
39
|
+
return payload;
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Key interfaces
|
|
44
|
+
|
|
45
|
+
| Type | Role |
|
|
46
|
+
|------|------|
|
|
47
|
+
| `ProjectManifest` | Top-level payload: `schemaVersion`, `story`, `generatedFrom`, `entities` |
|
|
48
|
+
| `EntityNode` | One introspected entity (id, display name, category, traits, source) |
|
|
49
|
+
| `TraitSummary` | Sparse, trait-keyed projection of the IDE-relevant fields |
|
|
50
|
+
| `SourceRef` | Resolved `file:line` of the entity's creation site |
|
|
51
|
+
| `EntityCategory` | `'room' \| 'object' \| 'npc' \| 'region'` |
|
|
52
|
+
|
|
53
|
+
## Related Packages
|
|
54
|
+
|
|
55
|
+
- [@sharpee/world-model](https://www.npmjs.com/package/@sharpee/world-model) - Source of the entities and traits the manifest projects
|
|
56
|
+
- [@sharpee/sharpee](https://www.npmjs.com/package/@sharpee/sharpee) - Full platform bundle (hosts the introspection emitter)
|
|
57
|
+
|
|
58
|
+
## License
|
|
59
|
+
|
|
60
|
+
MIT
|