@nimbalyst/extension-sdk 0.2.0 → 0.2.2

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.
Files changed (79) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +32 -0
  3. package/dist/__tests__/createTextCollabContentAdapter.test.d.ts +2 -0
  4. package/dist/__tests__/createTextCollabContentAdapter.test.d.ts.map +1 -0
  5. package/dist/__tests__/createTextCollabContentAdapter.test.js +60 -0
  6. package/dist/__tests__/externalsPlugin.test.d.ts +2 -0
  7. package/dist/__tests__/externalsPlugin.test.d.ts.map +1 -0
  8. package/dist/__tests__/externalsPlugin.test.js +16 -0
  9. package/dist/__tests__/fileDirectoryTree.test.d.ts +2 -0
  10. package/dist/__tests__/fileDirectoryTree.test.d.ts.map +1 -0
  11. package/dist/__tests__/fileDirectoryTree.test.js +54 -0
  12. package/dist/__tests__/hasSeedableContent.test.d.ts +2 -0
  13. package/dist/__tests__/hasSeedableContent.test.d.ts.map +1 -0
  14. package/dist/__tests__/hasSeedableContent.test.js +25 -0
  15. package/dist/__tests__/manifestValidation.agentProviders.test.d.ts +2 -0
  16. package/dist/__tests__/manifestValidation.agentProviders.test.d.ts.map +1 -0
  17. package/dist/__tests__/manifestValidation.agentProviders.test.js +44 -0
  18. package/dist/agents/AgentProtocol.d.ts +233 -0
  19. package/dist/agents/AgentProtocol.d.ts.map +1 -0
  20. package/dist/agents/AgentProtocol.js +23 -0
  21. package/dist/agents/AgentProtocolHost.d.ts +190 -0
  22. package/dist/agents/AgentProtocolHost.d.ts.map +1 -0
  23. package/dist/agents/AgentProtocolHost.js +42 -0
  24. package/dist/agents/index.d.ts +26 -0
  25. package/dist/agents/index.d.ts.map +1 -0
  26. package/dist/agents/index.js +24 -0
  27. package/dist/collab/createTextCollabContentAdapter.d.ts +26 -0
  28. package/dist/collab/createTextCollabContentAdapter.d.ts.map +1 -0
  29. package/dist/collab/createTextCollabContentAdapter.js +79 -0
  30. package/dist/externalsPlugin.js +10 -0
  31. package/dist/fileDirectoryTree.d.ts +19 -0
  32. package/dist/fileDirectoryTree.d.ts.map +1 -0
  33. package/dist/fileDirectoryTree.js +98 -0
  34. package/dist/index.d.ts +5 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +7 -0
  37. package/dist/manifestValidation.d.ts +118 -0
  38. package/dist/manifestValidation.d.ts.map +1 -0
  39. package/dist/manifestValidation.js +475 -0
  40. package/dist/trackerReferences.d.ts +32 -0
  41. package/dist/trackerReferences.d.ts.map +1 -0
  42. package/dist/trackerReferences.js +7 -0
  43. package/dist/types/collab.d.ts +138 -0
  44. package/dist/types/collab.d.ts.map +1 -0
  45. package/dist/types/collab.js +1 -0
  46. package/dist/types/editor.d.ts +81 -0
  47. package/dist/types/editor.d.ts.map +1 -1
  48. package/dist/types/editors.d.ts +4 -0
  49. package/dist/types/editors.d.ts.map +1 -1
  50. package/dist/types/extension.d.ts +364 -5
  51. package/dist/types/extension.d.ts.map +1 -1
  52. package/dist/types/extension.js +11 -1
  53. package/dist/types/index.d.ts +3 -0
  54. package/dist/types/index.d.ts.map +1 -1
  55. package/dist/types/index.js +3 -0
  56. package/dist/types/panel.d.ts +50 -0
  57. package/dist/types/panel.d.ts.map +1 -1
  58. package/dist/types/permissions.d.ts +119 -0
  59. package/dist/types/permissions.d.ts.map +1 -0
  60. package/dist/types/permissions.js +33 -0
  61. package/dist/types/theme.d.ts +50 -0
  62. package/dist/types/theme.d.ts.map +1 -1
  63. package/dist/types/theme.js +7 -1
  64. package/dist/types/trackerImporter.d.ts +147 -0
  65. package/dist/types/trackerImporter.d.ts.map +1 -0
  66. package/dist/types/trackerImporter.js +33 -0
  67. package/dist/useCollaborativeEditor.d.ts +84 -30
  68. package/dist/useCollaborativeEditor.d.ts.map +1 -1
  69. package/dist/useCollaborativeEditor.js +98 -7
  70. package/dist/validate.browser.d.ts +5 -0
  71. package/dist/validate.browser.d.ts.map +1 -0
  72. package/dist/validate.browser.js +27 -0
  73. package/dist/validate.d.ts +2 -8
  74. package/dist/validate.d.ts.map +1 -1
  75. package/dist/validate.js +117 -0
  76. package/dist/validationTypes.d.ts +9 -0
  77. package/dist/validationTypes.d.ts.map +1 -0
  78. package/dist/validationTypes.js +1 -0
  79. package/package.json +8 -1
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Extension permission types.
3
+ *
4
+ * The catalog of valid permission ids is owned by the host (Nimbalyst core).
5
+ * Extensions reference permission ids; they cannot register new ids.
6
+ *
7
+ * Scope of what this catalog actually enforces
8
+ * --------------------------------------------
9
+ * The catalog only contains permissions for capabilities Nimbalyst exposes
10
+ * through main-process brokers (database, workspace files, MCP registration,
11
+ * secrets). Brokers can refuse a call when the grant is missing, so these
12
+ * checks are real.
13
+ *
14
+ * The catalog deliberately does NOT contain ids for ambient Node capabilities
15
+ * like spawn-process, raw fs access, or arbitrary network. Once a backend
16
+ * module is granted (see BackendModuleContribution below), it can call
17
+ * `require('child_process')`, `require('fs')`, `require('net')` directly --
18
+ * there is no in-process sandbox that can prevent that. Listing those as
19
+ * granular permissions would advertise enforcement we cannot deliver.
20
+ *
21
+ * Instead, granting a backend module is itself the consent that "this
22
+ * extension may run native code on this machine with the same trust as your
23
+ * user account." The first-use prompt says this verbatim. Anything finer
24
+ * than that requires OS sandboxing or a different runtime model and is not
25
+ * in scope here.
26
+ *
27
+ * Risk tiers shape how the consent prompt groups brokered permissions:
28
+ * low - routine, low-impact (e.g., reading workspace files)
29
+ * elevated - non-trivial but bounded (e.g., registering MCP tools)
30
+ * high - powerful, broad impact (e.g., writing the host DB, reading
31
+ * secrets)
32
+ */
33
+ export type PermissionRiskTier = 'low' | 'elevated' | 'high';
34
+ /**
35
+ * The full set of permission ids understood by the host. Every entry here is
36
+ * a host-brokered capability: the renderer or backend module calls a main-
37
+ * process surface that consults the grant before running.
38
+ *
39
+ * Adding a new id here is a coordinated host change: the runtime catalog
40
+ * in the privileged host's `permissionRegistry` must gain a matching entry.
41
+ *
42
+ * Database access splits into read and write so extensions can declare
43
+ * least-privilege intent without composing two grants into one.
44
+ */
45
+ export type ExtensionPermissionId = 'workspace-files' | 'nimbalyst-database-read' | 'nimbalyst-database-write' | 'secrets-read' | 'mcp-server-register';
46
+ /**
47
+ * Backend module runtime. The privileged host loads the module in one of two
48
+ * isolated runtimes. Choose based on workload:
49
+ *
50
+ * utility-process - separate OS process via Electron `utilityProcess.fork`.
51
+ * Use for process-spawning, networked, or crash-prone
52
+ * backends (kernels, language servers, daemons).
53
+ * worker-thread - `node:worker_threads`. Use for lighter compute / indexing
54
+ * helpers that share the main-process Node lifecycle but
55
+ * run off the event loop.
56
+ */
57
+ export type BackendModuleRuntime = 'utility-process' | 'worker-thread';
58
+ /**
59
+ * How a privileged capability is enabled.
60
+ *
61
+ * `default: 'disabled'` is the only supported value today. Capabilities are
62
+ * always opt-in by the user.
63
+ *
64
+ * `promptOn: 'firstUse'` defers the consent prompt until the user takes an
65
+ * action that needs the capability. This avoids first-launch consent walls.
66
+ *
67
+ * `purpose` is a one-sentence, human-readable description shown verbatim in
68
+ * the consent prompt. It is the actual security copy the user reads, so
69
+ * write it from the user's perspective ("Run Jupyter kernels and execute
70
+ * notebook cells locally."), not the implementation's.
71
+ */
72
+ export interface BackendModuleEnablement {
73
+ default: 'disabled';
74
+ promptOn: 'firstUse';
75
+ purpose: string;
76
+ }
77
+ /**
78
+ * A backend module contributed by an extension.
79
+ *
80
+ * Backend modules live outside the renderer in the privileged host. They are
81
+ * inert until the user grants the module at first use.
82
+ *
83
+ * Granting a backend module is itself the consent to run native code on the
84
+ * user's machine. The catalog ids in `permissions` only cover ADDITIONAL
85
+ * host-brokered capabilities (Nimbalyst DB, secrets, MCP registration). They
86
+ * do NOT enumerate raw Node capabilities the module already has via standard
87
+ * `require()`. See the catalog docs at the top of this file.
88
+ *
89
+ * Any extension may declare a backend module. There is no provenance gate --
90
+ * installing an extension and approving its first-use consent prompt IS the
91
+ * decision to let it run native code. Built-in extensions ship inside the app
92
+ * bundle (same trust domain as the app), so the host auto-grants them and
93
+ * skips the prompt.
94
+ *
95
+ * `entry` is a path relative to the extension root pointing at a compiled JS
96
+ * file. The file is loaded inside the chosen runtime, never in Electron main.
97
+ */
98
+ export interface BackendModuleContribution {
99
+ /** Unique within the extension (e.g., "jupyter-runtime") */
100
+ id: string;
101
+ /** Path to compiled JS entry, relative to extension root */
102
+ entry: string;
103
+ /** Which isolated runtime hosts the module */
104
+ runtime: BackendModuleRuntime;
105
+ /**
106
+ * Additional host-brokered permissions this module requires beyond the
107
+ * implicit "run native code" grant. Optional -- a module that only needs
108
+ * ambient Node capabilities (fs, net, child_process) declares an empty
109
+ * array. The consent prompt always shows the "run native code" line; the
110
+ * brokered ids here appear as additional checkboxes grouped by risk tier.
111
+ *
112
+ * The runtime gate refuses any host-brokered RPC call whose permission is
113
+ * not in this list and not in the user's grant set.
114
+ */
115
+ permissions: ExtensionPermissionId[];
116
+ /** How/when the user is asked to enable this module */
117
+ enablement: BackendModuleEnablement;
118
+ }
119
+ //# sourceMappingURL=permissions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/types/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,yBAAyB,GACzB,0BAA0B,GAC1B,cAAc,GACd,qBAAqB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IAEX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,OAAO,EAAE,oBAAoB,CAAC;IAE9B;;;;;;;;;OASG;IACH,WAAW,EAAE,qBAAqB,EAAE,CAAC;IAErC,uDAAuD;IACvD,UAAU,EAAE,uBAAuB,CAAC;CACrC"}
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Extension permission types.
3
+ *
4
+ * The catalog of valid permission ids is owned by the host (Nimbalyst core).
5
+ * Extensions reference permission ids; they cannot register new ids.
6
+ *
7
+ * Scope of what this catalog actually enforces
8
+ * --------------------------------------------
9
+ * The catalog only contains permissions for capabilities Nimbalyst exposes
10
+ * through main-process brokers (database, workspace files, MCP registration,
11
+ * secrets). Brokers can refuse a call when the grant is missing, so these
12
+ * checks are real.
13
+ *
14
+ * The catalog deliberately does NOT contain ids for ambient Node capabilities
15
+ * like spawn-process, raw fs access, or arbitrary network. Once a backend
16
+ * module is granted (see BackendModuleContribution below), it can call
17
+ * `require('child_process')`, `require('fs')`, `require('net')` directly --
18
+ * there is no in-process sandbox that can prevent that. Listing those as
19
+ * granular permissions would advertise enforcement we cannot deliver.
20
+ *
21
+ * Instead, granting a backend module is itself the consent that "this
22
+ * extension may run native code on this machine with the same trust as your
23
+ * user account." The first-use prompt says this verbatim. Anything finer
24
+ * than that requires OS sandboxing or a different runtime model and is not
25
+ * in scope here.
26
+ *
27
+ * Risk tiers shape how the consent prompt groups brokered permissions:
28
+ * low - routine, low-impact (e.g., reading workspace files)
29
+ * elevated - non-trivial but bounded (e.g., registering MCP tools)
30
+ * high - powerful, broad impact (e.g., writing the host DB, reading
31
+ * secrets)
32
+ */
33
+ export {};
@@ -14,6 +14,56 @@ export type ThemeColorKey = 'bg' | 'bg-secondary' | 'bg-tertiary' | 'bg-hover' |
14
14
  * All colors are optional - missing colors will fall back to base theme.
15
15
  */
16
16
  export type ThemeColors = Partial<Record<ThemeColorKey, string>>;
17
+ /**
18
+ * Built-in Monaco theme ids accepted as the `base` field on a
19
+ * `MonacoThemeContribution`. Single source of truth -- the manifest
20
+ * validator, the renderer registry helper, and consumer-facing docs
21
+ * all derive from this list.
22
+ */
23
+ export declare const MONACO_BASE_THEMES: readonly ["vs", "vs-dark", "hc-black", "hc-light"];
24
+ export type MonacoBaseTheme = typeof MONACO_BASE_THEMES[number];
25
+ /**
26
+ * Monaco editor token rule -- mirrors monaco-editor's
27
+ * `editor.ITokenThemeRule`. Keeping the shape redeclared (rather than
28
+ * importing from monaco-editor) so extension manifests can be validated
29
+ * and processed in contexts that don't bundle Monaco.
30
+ */
31
+ export interface MonacoTokenRule {
32
+ /** Token id (e.g. 'comment', 'keyword.js', 'string.escape') */
33
+ token: string;
34
+ /** Hex color WITHOUT leading '#' (Monaco convention) */
35
+ foreground?: string;
36
+ /** Hex color WITHOUT leading '#' */
37
+ background?: string;
38
+ /** Space-separated styles: 'italic', 'bold', 'underline' */
39
+ fontStyle?: string;
40
+ }
41
+ /**
42
+ * Monaco editor theme contribution embedded in a ThemeContribution.
43
+ * When present, the runtime registers a matching Monaco theme via
44
+ * `monaco.editor.defineTheme()` and routes Monaco-backed editors
45
+ * (code files, JSON, etc.) to use it.
46
+ *
47
+ * `base` selects the Monaco built-in theme to inherit from. `rules`
48
+ * carries token-level color rules; `colors` carries Monaco's
49
+ * editor.* color keys (e.g. 'editor.background').
50
+ */
51
+ export interface MonacoThemeContribution {
52
+ /** Built-in Monaco theme used as the base for inheritance */
53
+ base: MonacoBaseTheme;
54
+ /**
55
+ * Whether to inherit unspecified rules/colors from `base`.
56
+ * Defaults to true (matches Monaco's `defineTheme` default).
57
+ */
58
+ inherit?: boolean;
59
+ /** Token rules applied to syntax-highlighted text */
60
+ rules: MonacoTokenRule[];
61
+ /**
62
+ * Editor color overrides keyed by Monaco color id
63
+ * (e.g. 'editor.background', 'editor.foreground').
64
+ */
65
+ colors: Record<string, string>;
66
+ }
17
67
  /**
18
68
  * Where a theme entry returned by `theme:list` originated from.
19
69
  */
@@ -1 +1 @@
1
- {"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/types/theme.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAErB,IAAI,GAAG,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,GAEhF,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,eAAe,GAEtD,QAAQ,GAAG,cAAc,GAEzB,SAAS,GAAG,eAAe,GAE3B,MAAM,GAAG,YAAY,GAErB,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IAEX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAE7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IAEX,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAEhB,aAAa;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,oBAAoB;IACpB,MAAM,EAAE,OAAO,CAAC;IAEhB,qDAAqD;IACrD,MAAM,EAAE,WAAW,CAAC;IAEpB,WAAW;IACX,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,0BAA0B;IAC1B,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IAEX,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IAEb,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IAEf,cAAc;IACd,OAAO,EAAE,MAAM,CAAC;IAEhB,kBAAkB;IAClB,WAAW,EAAE,MAAM,CAAC;IAEpB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAElB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW;IACX,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAEhB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IAEpB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IAEpB,cAAc;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,mBAAmB;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAC;IAEf,iCAAiC;IACjC,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAEhB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}
1
+ {"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/types/theme.ts"],"names":[],"mappings":"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"}
@@ -4,4 +4,10 @@
4
4
  * Themes are separate from extensions - they provide styling only, no code.
5
5
  * This module defines the schema for theme.json manifests and theme metadata.
6
6
  */
7
- export {};
7
+ /**
8
+ * Built-in Monaco theme ids accepted as the `base` field on a
9
+ * `MonacoThemeContribution`. Single source of truth -- the manifest
10
+ * validator, the renderer registry helper, and consumer-facing docs
11
+ * all derive from this list.
12
+ */
13
+ export const MONACO_BASE_THEMES = ['vs', 'vs-dark', 'hc-black', 'hc-light'];
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Tracker importer contract.
3
+ *
4
+ * An importer lets Nimbalyst pull items from an external system (GitHub Issues,
5
+ * Linear, ...) into the native tracker as ordinary items that carry a back-link
6
+ * to their upstream source (see the `origin` field on tracker items).
7
+ *
8
+ * This is a strict READ-side, one-shot subset of the broader `TrackerProvider`
9
+ * design: `listBindings` + `list` + `fetch` are enough to power snapshot import.
10
+ * Write/sync/comment methods can be added later as optional methods without
11
+ * breaking importers written against this contract.
12
+ *
13
+ * ## Runtime model
14
+ *
15
+ * Importers do privileged work (network calls, spawning `gh`, reading tokens),
16
+ * so the implementation runs inside the extension's **backend module**
17
+ * (utility-process) — not the renderer. The methods below are the RPC surface
18
+ * the backend module exports under the `importer.*` namespace; the host's
19
+ * `TrackerImporterRegistry` invokes them and owns turning a {@link TrackerSnapshot}
20
+ * into a real tracker item through the normal create path (so sync, body Y.Doc,
21
+ * activity, and issue-key allocation all fire identically to a hand-created item).
22
+ *
23
+ * The contribution therefore points at a `backendModuleId` (declared in
24
+ * `contributions.backendModules`) rather than a renderer component.
25
+ */
26
+ /** Method names the importer backend module must export, namespaced `importer.*`. */
27
+ export declare const TRACKER_IMPORTER_RPC_METHODS: {
28
+ readonly isAuthenticated: "importer.isAuthenticated";
29
+ readonly listBindings: "importer.listBindings";
30
+ readonly list: "importer.list";
31
+ readonly fetch: "importer.fetch";
32
+ readonly openExternal: "importer.openExternal";
33
+ };
34
+ /**
35
+ * Manifest declaration for an importer. Lives in
36
+ * `contributions.trackerImporters[]`.
37
+ */
38
+ export interface TrackerImporterContribution {
39
+ /** Stable id, kebab-case. Used as the `providerId` on imported items' origin. */
40
+ id: string;
41
+ /** Human-readable name, e.g. 'GitHub Issues'. */
42
+ displayName: string;
43
+ /** Material icon name, e.g. 'bug_report'. */
44
+ icon: string;
45
+ /** URN scheme this importer owns, e.g. 'github' | 'linear'. Routes by URN. */
46
+ urnScheme: string;
47
+ /**
48
+ * Id of the backend module (from `contributions.backendModules`) that
49
+ * implements the `importer.*` RPC methods.
50
+ */
51
+ backendModuleId: string;
52
+ /** Tracker types this importer may create. Empty/undefined = any creatable type. */
53
+ importsAs?: string[];
54
+ /** Settings panel id (from `contributions.settingsPanel`) handling auth + bindings. */
55
+ settingsPanelId?: string;
56
+ }
57
+ /** A configured import target within a provider (a GitHub repo, a Linear team, ...). */
58
+ export interface ImporterBinding {
59
+ /** Per-binding id, e.g. 'nimbalyst/nimbalyst' for a GitHub repo. */
60
+ id: string;
61
+ /** Human-readable label for the binding chooser. */
62
+ label: string;
63
+ }
64
+ /** Advisory filters for {@link ImporterMethods.list}. The importer applies what it supports. */
65
+ export interface ImporterListFilter {
66
+ search?: string;
67
+ state?: 'open' | 'closed' | 'all';
68
+ labels?: string[];
69
+ cursor?: string;
70
+ limit?: number;
71
+ }
72
+ /** Lightweight list entry; the full body is fetched lazily via {@link ImporterMethods.fetch}. */
73
+ export interface ImporterListEntry {
74
+ externalId: string;
75
+ urn: string;
76
+ url: string;
77
+ title: string;
78
+ state: string;
79
+ updatedAt: string;
80
+ }
81
+ export interface ImporterListPage {
82
+ items: ImporterListEntry[];
83
+ nextCursor?: string;
84
+ }
85
+ /** Identity of an upstream author, matching the host's tracker identity shape. */
86
+ export interface ImporterIdentity {
87
+ email: string | null;
88
+ displayName: string;
89
+ gitName?: string | null;
90
+ gitEmail?: string | null;
91
+ }
92
+ /**
93
+ * Pointer to the upstream record, minus the host-stamped timestamps
94
+ * (`importedAt` / `lastSyncedAt`), which the host fills in on import.
95
+ */
96
+ export interface ImporterExternalRef {
97
+ providerId: string;
98
+ externalId: string;
99
+ urn: string;
100
+ url: string;
101
+ titleSnapshot: string;
102
+ stateSnapshot?: string;
103
+ }
104
+ /**
105
+ * One-shot snapshot returned by {@link ImporterMethods.fetch}. The host converts
106
+ * this into a tracker item (markdown body -> Lexical state, status mapped to a
107
+ * workspace status, etc.).
108
+ */
109
+ export interface TrackerSnapshot {
110
+ external: ImporterExternalRef;
111
+ /** Tracker type to create as; importer picks from its `importsAs`. */
112
+ primaryType: string;
113
+ title: string;
114
+ /** Markdown body; host converts to Lexical content on insert. */
115
+ body?: string;
116
+ status?: string;
117
+ priority?: string;
118
+ labels?: string[];
119
+ authorIdentity?: ImporterIdentity | null;
120
+ upstreamCreatedAt?: string;
121
+ upstreamUpdatedAt?: string;
122
+ }
123
+ /**
124
+ * The RPC surface an importer backend module implements. Each method maps to a
125
+ * `TRACKER_IMPORTER_RPC_METHODS` entry. All are async (they cross the
126
+ * backend-module RPC boundary).
127
+ */
128
+ export interface ImporterMethods {
129
+ /** Has the user authenticated this importer? UI hides import flows otherwise. */
130
+ isAuthenticated(): Promise<boolean>;
131
+ /** Per-workspace targets the user configured (repos, teams). */
132
+ listBindings(): Promise<ImporterBinding[]>;
133
+ /** Page through importable items for one binding. */
134
+ list(args: {
135
+ binding: ImporterBinding;
136
+ filters: ImporterListFilter;
137
+ }): Promise<ImporterListPage>;
138
+ /** Pull one external item as a snapshot. One-shot read; the host decides create vs merge. */
139
+ fetch(args: {
140
+ externalId: string;
141
+ }): Promise<TrackerSnapshot>;
142
+ /** Optional: open the external item in the default browser. */
143
+ openExternal?(args: {
144
+ externalId: string;
145
+ }): Promise<void>;
146
+ }
147
+ //# sourceMappingURL=trackerImporter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trackerImporter.d.ts","sourceRoot":"","sources":["../../src/types/trackerImporter.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Tracker importer contract.
3
+ *
4
+ * An importer lets Nimbalyst pull items from an external system (GitHub Issues,
5
+ * Linear, ...) into the native tracker as ordinary items that carry a back-link
6
+ * to their upstream source (see the `origin` field on tracker items).
7
+ *
8
+ * This is a strict READ-side, one-shot subset of the broader `TrackerProvider`
9
+ * design: `listBindings` + `list` + `fetch` are enough to power snapshot import.
10
+ * Write/sync/comment methods can be added later as optional methods without
11
+ * breaking importers written against this contract.
12
+ *
13
+ * ## Runtime model
14
+ *
15
+ * Importers do privileged work (network calls, spawning `gh`, reading tokens),
16
+ * so the implementation runs inside the extension's **backend module**
17
+ * (utility-process) — not the renderer. The methods below are the RPC surface
18
+ * the backend module exports under the `importer.*` namespace; the host's
19
+ * `TrackerImporterRegistry` invokes them and owns turning a {@link TrackerSnapshot}
20
+ * into a real tracker item through the normal create path (so sync, body Y.Doc,
21
+ * activity, and issue-key allocation all fire identically to a hand-created item).
22
+ *
23
+ * The contribution therefore points at a `backendModuleId` (declared in
24
+ * `contributions.backendModules`) rather than a renderer component.
25
+ */
26
+ /** Method names the importer backend module must export, namespaced `importer.*`. */
27
+ export const TRACKER_IMPORTER_RPC_METHODS = {
28
+ isAuthenticated: 'importer.isAuthenticated',
29
+ listBindings: 'importer.listBindings',
30
+ list: 'importer.list',
31
+ fetch: 'importer.fetch',
32
+ openExternal: 'importer.openExternal',
33
+ };
@@ -37,6 +37,7 @@
37
37
  */
38
38
  import * as Y from 'yjs';
39
39
  import type { CollaborationStatus, CollaboratorInfo, EditorHost } from './types/editor.js';
40
+ import type { CollabCodec } from './types/collab.js';
40
41
  /**
41
42
  * Origin tag used when the SDK wraps `initializeFromContent` in a Y.Doc
42
43
  * transaction. Extension bindings can compare a transaction's origin
@@ -51,44 +52,83 @@ import type { CollaborationStatus, CollaboratorInfo, EditorHost } from './types/
51
52
  * ```
52
53
  */
53
54
  export declare const COLLAB_INIT_ORIGIN: unique symbol;
54
- export interface UseCollaborativeEditorConfig {
55
+ /** Context passed to the binding factory (`bind` / `createBinding`). */
56
+ export interface CollabBindContext {
57
+ yDoc: Y.Doc;
58
+ awareness: import('y-protocols/awareness').Awareness;
59
+ user: {
60
+ id: string;
61
+ name: string;
62
+ color: string;
63
+ };
64
+ }
65
+ export type CollabBindResult = {
66
+ destroy: () => void;
67
+ } | Promise<{
68
+ destroy: () => void;
69
+ }>;
70
+ /**
71
+ * Preferred config: pass the SAME pure {@link CollabCodec} the extension
72
+ * registered via `context.services.collab.registerContentAdapter(...)`, plus
73
+ * the one React-coupled piece (`bind`). `isEmpty` / `seedFromFile` are read
74
+ * off the codec, so the live seed and every headless seed provably run the
75
+ * same code -- an extension can no longer implement emptiness/seeding twice
76
+ * and have the two disagree.
77
+ *
78
+ * ```tsx
79
+ * useCollaborativeEditor(host, {
80
+ * codec: mindmapCodec,
81
+ * bind: ({ yDoc, awareness, user }) => new MindmapBinding(yDoc, api, awareness),
82
+ * });
83
+ * ```
84
+ */
85
+ export interface UseCollaborativeEditorCodecConfig {
86
+ /** The pure codec. Its `isEmpty` gates seeding and `seedFromFile` performs it. */
87
+ codec: CollabCodec;
55
88
  /**
56
- * Create the yJS binding that wires editor state to the Y.Doc. Called
57
- * once when collaboration is ready (sync done, seed applied if needed).
58
- * Returns a destroy fn invoked on unmount or when the binding needs to
59
- * be torn down.
89
+ * Create the yJS binding that wires editor state to the Y.Doc. Called once
90
+ * when collaboration is ready (sync done, seed applied if needed). May return
91
+ * a Promise so extensions can defer construction until their imperative API
92
+ * has finished mounting; the hook awaits it and honors cancellation.
60
93
  */
61
- createBinding(ctx: {
62
- yDoc: Y.Doc;
63
- awareness: import('y-protocols/awareness').Awareness;
64
- user: {
65
- id: string;
66
- name: string;
67
- color: string;
68
- };
69
- }): {
70
- destroy: () => void;
71
- };
94
+ bind(ctx: CollabBindContext): CollabBindResult;
72
95
  /**
73
- * Decide whether the Y.Doc still needs to be seeded from file content.
74
- * Returning `true` means "this Y.Doc has no extension content yet -- call
75
- * initializeFromContent". Default: `Y.encodeStateAsUpdate(yDoc).byteLength <= 2`,
76
- * which matches a fully empty Y.Doc.
77
- *
78
- * Override when your shared types may exist as empty containers (e.g. you
79
- * always call `yDoc.getMap('meta')` even on first open) and a length-2
80
- * encoded state would still be considered "empty" by your check.
96
+ * Optional: notified when the first-open seed fails or its flush is not
97
+ * confirmed by the server. The host uses this to surface the failure via the
98
+ * pending-seed machinery instead of leaving a silent `console.error`.
99
+ */
100
+ onSeedOutcome?(outcome: {
101
+ ok: boolean;
102
+ error?: unknown;
103
+ }): void;
104
+ }
105
+ /**
106
+ * @deprecated Legacy config shape. Prefer {@link UseCollaborativeEditorCodecConfig}
107
+ * (`{ codec, bind }`), which keeps the pure `isEmpty`/`seed` on the codec so
108
+ * live and headless seeding cannot diverge. This shape traps those pure
109
+ * functions inside React. Still accepted so existing editors keep working.
110
+ */
111
+ export interface UseCollaborativeEditorLegacyConfig {
112
+ /** @deprecated Use `bind` on the codec config. */
113
+ createBinding(ctx: CollabBindContext): CollabBindResult;
114
+ /**
115
+ * @deprecated Provide `isEmpty` on the codec. Decide whether the Y.Doc still
116
+ * needs seeding from file content. Default: `Y.encodeStateAsUpdate(yDoc).byteLength <= 2`.
81
117
  */
82
118
  isEmpty?(yDoc: Y.Doc): boolean;
83
119
  /**
84
- * Populate the Y.Doc from raw file content when this client is the first
85
- * to open the document. Called inside a `yDoc.transact(..., COLLAB_INIT_ORIGIN)`
86
- * so bindings can ignore the seeding transaction.
87
- *
88
- * Bootstrap race: see file-level docs. Use content-derived stable IDs.
120
+ * @deprecated Provide `seedFromFile` on the codec. Populate the Y.Doc from
121
+ * raw file content when this client is first. Called inside a
122
+ * `yDoc.transact(..., COLLAB_INIT_ORIGIN)`. Use content-derived stable IDs
123
+ * (see file-level docs) to keep the bootstrap race deterministic.
89
124
  */
90
125
  initializeFromContent(yDoc: Y.Doc, content: string | ArrayBuffer): void;
126
+ onSeedOutcome?(outcome: {
127
+ ok: boolean;
128
+ error?: unknown;
129
+ }): void;
91
130
  }
131
+ export type UseCollaborativeEditorConfig = UseCollaborativeEditorCodecConfig | UseCollaborativeEditorLegacyConfig;
92
132
  export interface UseCollaborativeEditorResult {
93
133
  /** True when `host.collaboration` is defined. */
94
134
  isCollaborative: boolean;
@@ -100,12 +140,26 @@ export interface UseCollaborativeEditorResult {
100
140
  */
101
141
  collaborators: Map<string, CollaboratorInfo>;
102
142
  /**
103
- * The binding handle once `createBinding` has run, or `null` until
143
+ * The binding handle once the binding factory has run, or `null` until
104
144
  * collaboration is ready / when not collab.
105
145
  */
106
146
  binding: {
107
147
  destroy: () => void;
108
148
  } | null;
149
+ /**
150
+ * Non-null when the first-open seed failed or its flush was not confirmed by
151
+ * the server. Hosts read this to surface the failure (pending-seed toast)
152
+ * rather than leaving a silent console error.
153
+ */
154
+ seedError: unknown | null;
109
155
  }
156
+ /**
157
+ * True when `content` can legitimately seed a first-open collaborative doc.
158
+ * Empty/whitespace content must never seed: the host returns '' when it has
159
+ * no bytes for the document (e.g. reopening an already-shared doc), and
160
+ * seeding from that writes a DEFAULT document into the shared room —
161
+ * clobbering the room's real content for every client. Exported for tests.
162
+ */
163
+ export declare function hasSeedableContent(content: string | ArrayBuffer | Uint8Array | null | undefined): boolean;
110
164
  export declare function useCollaborativeEditor(host: EditorHost, config: UseCollaborativeEditorConfig): UseCollaborativeEditorResult;
111
165
  //# sourceMappingURL=useCollaborativeEditor.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useCollaborativeEditor.d.ts","sourceRoot":"","sources":["../src/useCollaborativeEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,eAAkC,CAAC;AAElE,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE;QACjB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC;QACZ,SAAS,EAAE,OAAO,uBAAuB,EAAE,SAAS,CAAC;QACrD,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KACnD,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAE5B;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC;IAE/B;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C;;;OAGG;IACH,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACzC;AAOD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,4BAA4B,GACnC,4BAA4B,CAwH9B"}
1
+ {"version":3,"file":"useCollaborativeEditor.d.ts","sourceRoot":"","sources":["../src/useCollaborativeEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,eAAkC,CAAC;AAElE,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC;IACZ,SAAS,EAAE,OAAO,uBAAuB,EAAE,SAAS,CAAC;IACrD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iCAAiC;IAChD,kFAAkF;IAClF,KAAK,EAAE,WAAW,CAAC;IAEnB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAE/C;;;;OAIG;IACH,aAAa,CAAC,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kCAAkC;IACjD,kDAAkD;IAClD,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAExD;;;OAGG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC;IAE/B;;;;;OAKG;IACH,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAExE,aAAa,CAAC,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACjE;AAED,MAAM,MAAM,4BAA4B,GACpC,iCAAiC,GACjC,kCAAkC,CAAC;AAEvC,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C;;;OAGG;IACH,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B;AAyCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,SAAS,GAC5D,OAAO,CAIT;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,4BAA4B,GACnC,4BAA4B,CAgL9B"}