@sharpee/ide-protocol 1.0.0

package/guards.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Type guards for the IDE introspection manifest wire types.
+ *
+ * Purpose: validate untrusted manifest JSON at the decode boundary (the IDE, and
+ *   the bridge/CLI round-trip tests) before it is treated as a {@link ProjectManifest}.
+ * Public interface: isProjectManifest, isEntityNode, isEntityCategory, isSourceRef.
+ * Owner context: @sharpee/ide-protocol (ADR-184). Pure predicates, no runtime deps.
+ */
+import type { ProjectManifest, EntityNode, EntityCategory, SourceRef } from './types';
+/** Narrow a value to a valid {@link EntityCategory}. */
+export declare function isEntityCategory(value: unknown): value is EntityCategory;
+/** Narrow a value to a valid {@link SourceRef}. */
+export declare function isSourceRef(value: unknown): value is SourceRef;
+/** Narrow a value to a valid {@link EntityNode}. `source`, when present, must be a valid SourceRef. */
+export declare function isEntityNode(value: unknown): value is EntityNode;
+/**
+ * Narrow a value to a valid {@link ProjectManifest}. Requires the schema version
+ * to match this package's {@link SCHEMA_VERSION} and every entity to be well-formed.
+ */
+export declare function isProjectManifest(value: unknown): value is ProjectManifest;
+//# sourceMappingURL=guards.d.ts.map

package/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../repos/sharpee/packages/ide-protocol/src/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,SAAS,EACV,MAAM,SAAS,CAAC;AAcjB,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAO9D;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAQhE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAO1E"}

package/guards.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Type guards for the IDE introspection manifest wire types.
+ *
+ * Purpose: validate untrusted manifest JSON at the decode boundary (the IDE, and
+ *   the bridge/CLI round-trip tests) before it is treated as a {@link ProjectManifest}.
+ * Public interface: isProjectManifest, isEntityNode, isEntityCategory, isSourceRef.
+ * Owner context: @sharpee/ide-protocol (ADR-184). Pure predicates, no runtime deps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEntityCategory = isEntityCategory;
+exports.isSourceRef = isSourceRef;
+exports.isEntityNode = isEntityNode;
+exports.isProjectManifest = isProjectManifest;
+const types_1 = require("./types");
+const CATEGORIES = new Set([
+    'room',
+    'object',
+    'npc',
+    'region',
+]);
+function isObject(v) {
+    return typeof v === 'object' && v !== null;
+}
+/** Narrow a value to a valid {@link EntityCategory}. */
+function isEntityCategory(value) {
+    return typeof value === 'string' && CATEGORIES.has(value);
+}
+/** Narrow a value to a valid {@link SourceRef}. */
+function isSourceRef(value) {
+    if (!isObject(value))
+        return false;
+    return (typeof value.file === 'string' &&
+        typeof value.line === 'number' &&
+        (value.resolution === 'exact' || value.resolution === 'scope'));
+}
+/** Narrow a value to a valid {@link EntityNode}. `source`, when present, must be a valid SourceRef. */
+function isEntityNode(value) {
+    if (!isObject(value))
+        return false;
+    if (typeof value.id !== 'string')
+        return false;
+    if (typeof value.displayName !== 'string')
+        return false;
+    if (!isEntityCategory(value.category))
+        return false;
+    if (!isObject(value.traits))
+        return false;
+    if ('source' in value && value.source !== undefined && !isSourceRef(value.source))
+        return false;
+    return true;
+}
+/**
+ * Narrow a value to a valid {@link ProjectManifest}. Requires the schema version
+ * to match this package's {@link SCHEMA_VERSION} and every entity to be well-formed.
+ */
+function isProjectManifest(value) {
+    if (!isObject(value))
+        return false;
+    if (value.schemaVersion !== types_1.SCHEMA_VERSION)
+        return false;
+    if (typeof value.story !== 'string')
+        return false;
+    if (value.generatedFrom !== 'cli' && value.generatedFrom !== 'bridge')
+        return false;
+    if (!Array.isArray(value.entities))
+        return false;
+    return value.entities.every(isEntityNode);
+}
+//# sourceMappingURL=guards.js.map

package/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../repos/sharpee/packages/ide-protocol/src/guards.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAsBH,4CAEC;AAGD,kCAOC;AAGD,oCAQC;AAMD,8CAOC;AAlDD,mCAAyC;AAEzC,MAAM,UAAU,GAAgC,IAAI,GAAG,CAAiB;IACtE,MAAM;IACN,QAAQ;IACR,KAAK;IACL,QAAQ;CACT,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC;AAC7C,CAAC;AAED,wDAAwD;AACxD,SAAgB,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,GAAG,CAAC,KAAuB,CAAC,CAAC;AAC9E,CAAC;AAED,mDAAmD;AACnD,SAAgB,WAAW,CAAC,KAAc;IACxC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,CACL,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAC9B,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAC9B,CAAC,KAAK,CAAC,UAAU,KAAK,OAAO,IAAI,KAAK,CAAC,UAAU,KAAK,OAAO,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED,uGAAuG;AACvG,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAChG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,KAAK,CAAC,aAAa,KAAK,sBAAc;QAAE,OAAO,KAAK,CAAC;IACzD,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,KAAK,CAAC,aAAa,KAAK,KAAK,IAAI,KAAK,CAAC,aAAa,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACpF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AAC5C,CAAC"}

package/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @sharpee/ide-protocol
+ *
+ * Shared wire types for the Sharpee IDE project-introspection manifest. The single
+ * source of truth for the contract between the platform's introspection emitters
+ * (the `--introspect` CLI and the Play-panel bridge) and the IDE that renders the
+ * Sharpee-aware project tree. Types only — no runtime dependencies — so both the
+ * Node emitter and the browser bridge import it cleanly (DEVARCH 8b).
+ *
+ * @packageDocumentation
+ * @see ADR-184: IDE project introspection via runtime world model
+ */
+export type { ProjectManifest, EntityNode, EntityCategory, SourceRef, TraitSummary, } from './types.js';
+export { SCHEMA_VERSION } from './types.js';
+export { isProjectManifest, isEntityNode, isEntityCategory, isSourceRef, } from './guards.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../repos/sharpee/packages/ide-protocol/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @sharpee/ide-protocol
+ *
+ * Shared wire types for the Sharpee IDE project-introspection manifest. The single
+ * source of truth for the contract between the platform's introspection emitters
+ * (the `--introspect` CLI and the Play-panel bridge) and the IDE that renders the
+ * Sharpee-aware project tree. Types only — no runtime dependencies — so both the
+ * Node emitter and the browser bridge import it cleanly (DEVARCH 8b).
+ *
+ * @packageDocumentation
+ * @see ADR-184: IDE project introspection via runtime world model
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSourceRef = exports.isEntityCategory = exports.isEntityNode = exports.isProjectManifest = exports.SCHEMA_VERSION = void 0;
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return types_js_1.SCHEMA_VERSION; } });
+var guards_js_1 = require("./guards.js");
+Object.defineProperty(exports, "isProjectManifest", { enumerable: true, get: function () { return guards_js_1.isProjectManifest; } });
+Object.defineProperty(exports, "isEntityNode", { enumerable: true, get: function () { return guards_js_1.isEntityNode; } });
+Object.defineProperty(exports, "isEntityCategory", { enumerable: true, get: function () { return guards_js_1.isEntityCategory; } });
+Object.defineProperty(exports, "isSourceRef", { enumerable: true, get: function () { return guards_js_1.isSourceRef; } });
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../repos/sharpee/packages/ide-protocol/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAUH,uCAA4C;AAAnC,0GAAA,cAAc,OAAA;AAEvB,yCAKqB;AAJnB,8GAAA,iBAAiB,OAAA;AACjB,yGAAA,YAAY,OAAA;AACZ,6GAAA,gBAAgB,OAAA;AAChB,wGAAA,WAAW,OAAA"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sharpee/ide-protocol",
+  "version": "1.0.0",
+  "description": "Wire types for the Sharpee IDE project-introspection manifest (ADR-184)",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "keywords": [
+    "interactive-fiction",
+    "if",
+    "sharpee",
+    "ide",
+    "introspection",
+    "protocol"
+  ],
+  "author": "Sharpee Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChicagoDave/sharpee.git",
+    "directory": "packages/ide-protocol"
+  },
+  "homepage": "https://github.com/ChicagoDave/sharpee#readme",
+  "bugs": {
+    "url": "https://github.com/ChicagoDave/sharpee/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Wire types for the Sharpee IDE project-introspection manifest.
+ *
+ * Purpose: the single, shared definition of the manifest the platform emits
+ *   (`--introspect` on the platform-bundle CLI, and the Play-panel WKWebView
+ *   bridge) and the IDE consumes. This is the wire contract; per DEVARCH 8b
+ *   it lives once and is imported by every same-language consumer.
+ * Public interface: ProjectManifest, EntityNode, EntityCategory, SourceRef,
+ *   TraitSummary, SCHEMA_VERSION.
+ * Owner context: @sharpee/ide-protocol (ADR-184). Types only — NO runtime-specific
+ *   types (no Buffer / fs / DOM), so both the Node emitter and the browser bridge
+ *   import it cleanly. The Swift IDE mirrors these shapes as Codable structs.
+ *
+ * @packageDocumentation
+ * @see ADR-184: IDE project introspection via runtime world model
+ */
+/** Current manifest schema version. Bump on any breaking shape change. */
+export declare const SCHEMA_VERSION: 1;
+/**
+ * The Sharpee-aware project tree, produced by running the story's world
+ * construction and projecting the resulting entities. A flat entity list plus a
+ * build-status header; the IDE buckets into categories client-side from
+ * {@link EntityNode.category}.
+ */
+export interface ProjectManifest {
+    /** Schema version; equals {@link SCHEMA_VERSION} for manifests this package emits. */
+    schemaVersion: typeof SCHEMA_VERSION;
+    /** Story id (from StoryConfig). */
+    story: string;
+    /** Which path produced this manifest. */
+    generatedFrom: 'cli' | 'bridge';
+    /** Every introspected entity, in world-enumeration order. */
+    entities: EntityNode[];
+}
+/** Top-level project-tree categories. Doors/exits surface under a room's `exits`. */
+export type EntityCategory = 'room' | 'object' | 'npc' | 'region';
+/** One introspected world entity. */
+export interface EntityNode {
+    /** World entity id. */
+    id: string;
+    /** IdentityTrait name (authored text) — the tree label. */
+    displayName: string;
+    /** Derived from the runtime trait set (see ADR-184 derivation table). */
+    category: EntityCategory;
+    /** Trait-type → the IDE-relevant fields (a projection, not the full trait). */
+    traits: TraitSummary;
+    /** file:line from the tree-sitter name index; absent when unresolved. */
+    source?: SourceRef;
+}
+/** A resolved source location for an entity's creation site. */
+export interface SourceRef {
+    /** Workspace-relative path. */
+    file: string;
+    /** 1-based line of the `createEntity('<name>', …)` site. */
+    line: number;
+    /** `'scope'` = fell back to the enclosing function (non-unique name). */
+    resolution: 'exact' | 'scope';
+}
+/**
+ * The fields the IDE renders/lints on, keyed by trait type. Sparse: a key is
+ * present only if the entity carries that trait. The index signature keeps the
+ * shape forward-compatible — unknown traits pass through without dropping the
+ * entity.
+ */
+export interface TraitSummary {
+    identity?: {
+        description?: string;
+    };
+    /** Exit directions present — drives the "room with no exits" lint. */
+    room?: {
+        exits: string[];
+    };
+    /** Co-trait lint inputs (e.g. "lockable without openable"). */
+    container?: {
+        openable: boolean;
+        lockable: boolean;
+    };
+    [traitType: string]: Record<string, unknown> | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../repos/sharpee/packages/ide-protocol/src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,cAAc,EAAG,CAAU,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,aAAa,EAAE,KAAK,GAAG,QAAQ,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;AAElE,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,QAAQ,EAAE,cAAc,CAAC;IACzB,+EAA+E;IAC/E,MAAM,EAAE,YAAY,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,gEAAgE;AAChE,MAAM,WAAW,SAAS;IACxB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,sEAAsE;IACtE,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC3B,+DAA+D;IAC/D,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACrD,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC1D"}

package/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Wire types for the Sharpee IDE project-introspection manifest.
+ *
+ * Purpose: the single, shared definition of the manifest the platform emits
+ *   (`--introspect` on the platform-bundle CLI, and the Play-panel WKWebView
+ *   bridge) and the IDE consumes. This is the wire contract; per DEVARCH 8b
+ *   it lives once and is imported by every same-language consumer.
+ * Public interface: ProjectManifest, EntityNode, EntityCategory, SourceRef,
+ *   TraitSummary, SCHEMA_VERSION.
+ * Owner context: @sharpee/ide-protocol (ADR-184). Types only — NO runtime-specific
+ *   types (no Buffer / fs / DOM), so both the Node emitter and the browser bridge
+ *   import it cleanly. The Swift IDE mirrors these shapes as Codable structs.
+ *
+ * @packageDocumentation
+ * @see ADR-184: IDE project introspection via runtime world model
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = void 0;
+/** Current manifest schema version. Bump on any breaking shape change. */
+exports.SCHEMA_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../repos/sharpee/packages/ide-protocol/src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,0EAA0E;AAC7D,QAAA,cAAc,GAAG,CAAU,CAAC"}