@principal-ai/principal-studio-cli 0.35.3

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 (184) hide show
  1. package/README.md +172 -0
  2. package/dist/commands/agent-session.d.ts +3 -0
  3. package/dist/commands/agent-session.d.ts.map +1 -0
  4. package/dist/commands/agent-session.js +67 -0
  5. package/dist/commands/agent-sessions.d.ts +11 -0
  6. package/dist/commands/agent-sessions.d.ts.map +1 -0
  7. package/dist/commands/agent-sessions.js +39 -0
  8. package/dist/commands/auxiliary/index.d.ts +3 -0
  9. package/dist/commands/auxiliary/index.d.ts.map +1 -0
  10. package/dist/commands/auxiliary/index.js +9 -0
  11. package/dist/commands/auxiliary/validate.d.ts +3 -0
  12. package/dist/commands/auxiliary/validate.d.ts.map +1 -0
  13. package/dist/commands/auxiliary/validate.js +123 -0
  14. package/dist/commands/collector/check.d.ts +6 -0
  15. package/dist/commands/collector/check.d.ts.map +1 -0
  16. package/dist/commands/collector/check.js +153 -0
  17. package/dist/commands/collector/diagnose.d.ts +6 -0
  18. package/dist/commands/collector/diagnose.d.ts.map +1 -0
  19. package/dist/commands/collector/diagnose.js +229 -0
  20. package/dist/commands/collector/index.d.ts +6 -0
  21. package/dist/commands/collector/index.d.ts.map +1 -0
  22. package/dist/commands/collector/index.js +16 -0
  23. package/dist/commands/collector/status.d.ts +6 -0
  24. package/dist/commands/collector/status.d.ts.map +1 -0
  25. package/dist/commands/collector/status.js +77 -0
  26. package/dist/commands/collector/utils.d.ts +92 -0
  27. package/dist/commands/collector/utils.d.ts.map +1 -0
  28. package/dist/commands/collector/utils.js +154 -0
  29. package/dist/commands/coverage.d.ts +9 -0
  30. package/dist/commands/coverage.d.ts.map +1 -0
  31. package/dist/commands/coverage.js +252 -0
  32. package/dist/commands/create.d.ts +6 -0
  33. package/dist/commands/create.d.ts.map +1 -0
  34. package/dist/commands/create.js +50 -0
  35. package/dist/commands/events/index.d.ts +3 -0
  36. package/dist/commands/events/index.d.ts.map +1 -0
  37. package/dist/commands/events/index.js +9 -0
  38. package/dist/commands/events/validate.d.ts +3 -0
  39. package/dist/commands/events/validate.d.ts.map +1 -0
  40. package/dist/commands/events/validate.js +124 -0
  41. package/dist/commands/formats.d.ts +6 -0
  42. package/dist/commands/formats.d.ts.map +1 -0
  43. package/dist/commands/formats.js +1118 -0
  44. package/dist/commands/hooks.d.ts +9 -0
  45. package/dist/commands/hooks.d.ts.map +1 -0
  46. package/dist/commands/hooks.js +295 -0
  47. package/dist/commands/inbox.d.ts +13 -0
  48. package/dist/commands/inbox.d.ts.map +1 -0
  49. package/dist/commands/inbox.js +179 -0
  50. package/dist/commands/init.d.ts +6 -0
  51. package/dist/commands/init.d.ts.map +1 -0
  52. package/dist/commands/init.js +220 -0
  53. package/dist/commands/lint.d.ts +11 -0
  54. package/dist/commands/lint.d.ts.map +1 -0
  55. package/dist/commands/lint.js +71 -0
  56. package/dist/commands/list.d.ts +6 -0
  57. package/dist/commands/list.d.ts.map +1 -0
  58. package/dist/commands/list.js +78 -0
  59. package/dist/commands/migrate-nodes.d.ts +9 -0
  60. package/dist/commands/migrate-nodes.d.ts.map +1 -0
  61. package/dist/commands/migrate-nodes.js +363 -0
  62. package/dist/commands/migrate-scopes-to-canvas.d.ts +3 -0
  63. package/dist/commands/migrate-scopes-to-canvas.d.ts.map +1 -0
  64. package/dist/commands/migrate-scopes-to-canvas.js +143 -0
  65. package/dist/commands/migration.d.ts +6 -0
  66. package/dist/commands/migration.d.ts.map +1 -0
  67. package/dist/commands/migration.js +247 -0
  68. package/dist/commands/open-studio.d.ts +10 -0
  69. package/dist/commands/open-studio.d.ts.map +1 -0
  70. package/dist/commands/open-studio.js +32 -0
  71. package/dist/commands/opencode/fetch.d.ts +3 -0
  72. package/dist/commands/opencode/fetch.d.ts.map +1 -0
  73. package/dist/commands/opencode/fetch.js +25 -0
  74. package/dist/commands/opencode/index.d.ts +3 -0
  75. package/dist/commands/opencode/index.d.ts.map +1 -0
  76. package/dist/commands/opencode/index.js +11 -0
  77. package/dist/commands/opencode/list-sessions.d.ts +3 -0
  78. package/dist/commands/opencode/list-sessions.d.ts.map +1 -0
  79. package/dist/commands/opencode/list-sessions.js +20 -0
  80. package/dist/commands/repo.d.ts +18 -0
  81. package/dist/commands/repo.d.ts.map +1 -0
  82. package/dist/commands/repo.js +233 -0
  83. package/dist/commands/schema.d.ts +6 -0
  84. package/dist/commands/schema.d.ts.map +1 -0
  85. package/dist/commands/schema.js +367 -0
  86. package/dist/commands/scopes/index.d.ts +3 -0
  87. package/dist/commands/scopes/index.d.ts.map +1 -0
  88. package/dist/commands/scopes/index.js +9 -0
  89. package/dist/commands/scopes/validate.d.ts +3 -0
  90. package/dist/commands/scopes/validate.d.ts.map +1 -0
  91. package/dist/commands/scopes/validate.js +187 -0
  92. package/dist/commands/setup.d.ts +6 -0
  93. package/dist/commands/setup.d.ts.map +1 -0
  94. package/dist/commands/setup.js +406 -0
  95. package/dist/commands/starred-collections.d.ts +12 -0
  96. package/dist/commands/starred-collections.d.ts.map +1 -0
  97. package/dist/commands/starred-collections.js +310 -0
  98. package/dist/commands/subsystem-model.d.ts +11 -0
  99. package/dist/commands/subsystem-model.d.ts.map +1 -0
  100. package/dist/commands/subsystem-model.js +249 -0
  101. package/dist/commands/topic.d.ts +15 -0
  102. package/dist/commands/topic.d.ts.map +1 -0
  103. package/dist/commands/topic.js +683 -0
  104. package/dist/commands/tour.d.ts +23 -0
  105. package/dist/commands/tour.d.ts.map +1 -0
  106. package/dist/commands/tour.js +783 -0
  107. package/dist/commands/trace/flow.d.ts +6 -0
  108. package/dist/commands/trace/flow.d.ts.map +1 -0
  109. package/dist/commands/trace/flow.js +158 -0
  110. package/dist/commands/trace/index.d.ts +6 -0
  111. package/dist/commands/trace/index.d.ts.map +1 -0
  112. package/dist/commands/trace/index.js +20 -0
  113. package/dist/commands/trace/inspect.d.ts +6 -0
  114. package/dist/commands/trace/inspect.d.ts.map +1 -0
  115. package/dist/commands/trace/inspect.js +187 -0
  116. package/dist/commands/trace/list.d.ts +6 -0
  117. package/dist/commands/trace/list.d.ts.map +1 -0
  118. package/dist/commands/trace/list.js +145 -0
  119. package/dist/commands/trace/registrations.d.ts +6 -0
  120. package/dist/commands/trace/registrations.d.ts.map +1 -0
  121. package/dist/commands/trace/registrations.js +81 -0
  122. package/dist/commands/trace/validate.d.ts +6 -0
  123. package/dist/commands/trace/validate.d.ts.map +1 -0
  124. package/dist/commands/trace/validate.js +276 -0
  125. package/dist/commands/trail.d.ts +36 -0
  126. package/dist/commands/trail.d.ts.map +1 -0
  127. package/dist/commands/trail.js +622 -0
  128. package/dist/commands/validate.d.ts +12 -0
  129. package/dist/commands/validate.d.ts.map +1 -0
  130. package/dist/commands/validate.js +3334 -0
  131. package/dist/commands/workflow/implementation.d.ts +3 -0
  132. package/dist/commands/workflow/implementation.d.ts.map +1 -0
  133. package/dist/commands/workflow/implementation.js +51 -0
  134. package/dist/commands/workflow/index.d.ts +3 -0
  135. package/dist/commands/workflow/index.d.ts.map +1 -0
  136. package/dist/commands/workflow/index.js +19 -0
  137. package/dist/commands/workflow/inspect.d.ts +3 -0
  138. package/dist/commands/workflow/inspect.d.ts.map +1 -0
  139. package/dist/commands/workflow/inspect.js +123 -0
  140. package/dist/commands/workflow/list.d.ts +3 -0
  141. package/dist/commands/workflow/list.d.ts.map +1 -0
  142. package/dist/commands/workflow/list.js +95 -0
  143. package/dist/commands/workflow/render.d.ts +3 -0
  144. package/dist/commands/workflow/render.d.ts.map +1 -0
  145. package/dist/commands/workflow/render.js +88 -0
  146. package/dist/commands/workflow/test.d.ts +3 -0
  147. package/dist/commands/workflow/test.d.ts.map +1 -0
  148. package/dist/commands/workflow/test.js +141 -0
  149. package/dist/commands/workflow/utils.d.ts +49 -0
  150. package/dist/commands/workflow/utils.d.ts.map +1 -0
  151. package/dist/commands/workflow/utils.js +164 -0
  152. package/dist/commands/workflow/validate.d.ts +3 -0
  153. package/dist/commands/workflow/validate.d.ts.map +1 -0
  154. package/dist/commands/workflow/validate.js +344 -0
  155. package/dist/file-utils.d.ts +15 -0
  156. package/dist/file-utils.d.ts.map +1 -0
  157. package/dist/file-utils.js +29 -0
  158. package/dist/index.cjs +285718 -0
  159. package/dist/index.cjs.map +7 -0
  160. package/dist/index.d.ts +8 -0
  161. package/dist/index.d.ts.map +1 -0
  162. package/dist/index.js +81 -0
  163. package/dist/lib/bridge-ipc.d.ts +29 -0
  164. package/dist/lib/bridge-ipc.d.ts.map +1 -0
  165. package/dist/lib/bridge-ipc.js +128 -0
  166. package/dist/lib/github-user.d.ts +17 -0
  167. package/dist/lib/github-user.d.ts.map +1 -0
  168. package/dist/lib/github-user.js +53 -0
  169. package/dist/lib/open-url.d.ts +11 -0
  170. package/dist/lib/open-url.d.ts.map +1 -0
  171. package/dist/lib/open-url.js +45 -0
  172. package/dist/lib/subsystem-model-store.d.ts +74 -0
  173. package/dist/lib/subsystem-model-store.d.ts.map +1 -0
  174. package/dist/lib/subsystem-model-store.js +292 -0
  175. package/dist/lib/tour-cache.d.ts +26 -0
  176. package/dist/lib/tour-cache.d.ts.map +1 -0
  177. package/dist/lib/tour-cache.js +46 -0
  178. package/dist/lib/trail-cache.d.ts +40 -0
  179. package/dist/lib/trail-cache.d.ts.map +1 -0
  180. package/dist/lib/trail-cache.js +97 -0
  181. package/dist/lib/viewer-ipc.d.ts +44 -0
  182. package/dist/lib/viewer-ipc.d.ts.map +1 -0
  183. package/dist/lib/viewer-ipc.js +68 -0
  184. package/package.json +68 -0
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Principal View CLI - Main entry point
3
+ *
4
+ * This CLI provides tools to validate and manage .canvas configuration files
5
+ * for the Principal View Framework.
6
+ */
7
+ export {};
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
package/dist/index.js ADDED
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Principal View CLI - Main entry point
3
+ *
4
+ * This CLI provides tools to validate and manage .canvas configuration files
5
+ * for the Principal View Framework.
6
+ */
7
+ import { Command } from 'commander';
8
+ import { createValidateCommand } from './commands/validate.js';
9
+ import { createInitCommand } from './commands/init.js';
10
+ import { createListCommand } from './commands/list.js';
11
+ import { createSchemaCommand } from './commands/schema.js';
12
+ import { createFormatsCommand } from './commands/formats.js';
13
+ import { createSetupCommand } from './commands/setup.js';
14
+ import { createHooksCommand } from './commands/hooks.js';
15
+ import { createCreateCommand } from './commands/create.js';
16
+ import { createLintCommand } from './commands/lint.js';
17
+ import { createCoverageCommand } from './commands/coverage.js';
18
+ import { createWorkflowCommand } from './commands/workflow/index.js';
19
+ import { createMigrationCommand } from './commands/migration.js';
20
+ import { createMigrateNodesCommand } from './commands/migrate-nodes.js';
21
+ import { createMigrateScopesCommand } from './commands/migrate-scopes-to-canvas.js';
22
+ import { createScopesCommand } from './commands/scopes/index.js';
23
+ import { createAuxiliaryCommand } from './commands/auxiliary/index.js';
24
+ import { createEventsCommand } from './commands/events/index.js';
25
+ import { createCollectorCommand } from './commands/collector/index.js';
26
+ import { createTraceCommand } from './commands/trace/index.js';
27
+ import { createTrailCommand } from './commands/trail.js';
28
+ import { createTourCommand } from './commands/tour.js';
29
+ import { createTopicCommand } from './commands/topic.js';
30
+ import { createInboxCommand } from './commands/inbox.js';
31
+ import { createStarredCollectionsCommand } from './commands/starred-collections.js';
32
+ import { createRepoCommand } from './commands/repo.js';
33
+ import { createOpencodeCommand } from './commands/opencode/index.js';
34
+ import { createAgentSessionsCommand } from './commands/agent-sessions.js';
35
+ import { createAgentSessionCommand } from './commands/agent-session.js';
36
+ import { createOpenStudioCommand } from './commands/open-studio.js';
37
+ import { createSubsystemModelCommand } from './commands/subsystem-model.js';
38
+ // Injected at bundle time via esbuild `define`; falls back for tsx dev runs.
39
+ const VERSION = typeof __CLI_VERSION__ !== "undefined" ? __CLI_VERSION__ : "0.0.0-dev";
40
+ const program = new Command();
41
+ program
42
+ .name('principal-ai')
43
+ .description('Principal AI CLI - Validate and manage .canvas configuration files')
44
+ .version(VERSION);
45
+ // Add commands in logical order
46
+ program.addCommand(createInitCommand());
47
+ program.addCommand(createCreateCommand());
48
+ program.addCommand(createValidateCommand()); // Comprehensive structural validation
49
+ program.addCommand(createLintCommand()); // Style and conventions
50
+ program.addCommand(createListCommand());
51
+ program.addCommand(createSchemaCommand());
52
+ program.addCommand(createFormatsCommand());
53
+ program.addCommand(createSetupCommand());
54
+ program.addCommand(createMigrationCommand()); // Migration guide
55
+ program.addCommand(createMigrateNodesCommand()); // Node type migration
56
+ program.addCommand(createMigrateScopesCommand()); // Scope migration to canvas
57
+ program.addCommand(createHooksCommand());
58
+ program.addCommand(createCoverageCommand());
59
+ program.addCommand(createWorkflowCommand());
60
+ program.addCommand(createScopesCommand());
61
+ program.addCommand(createAuxiliaryCommand());
62
+ program.addCommand(createEventsCommand());
63
+ program.addCommand(createCollectorCommand());
64
+ program.addCommand(createTraceCommand());
65
+ program.addCommand(createTrailCommand());
66
+ program.addCommand(createTourCommand());
67
+ program.addCommand(createTopicCommand());
68
+ program.addCommand(createInboxCommand());
69
+ program.addCommand(createStarredCollectionsCommand());
70
+ program.addCommand(createRepoCommand());
71
+ program.addCommand(createOpencodeCommand());
72
+ program.addCommand(createOpenStudioCommand());
73
+ program.addCommand(createSubsystemModelCommand());
74
+ program.addCommand(createAgentSessionsCommand());
75
+ program.addCommand(createAgentSessionCommand());
76
+ // Parse command line arguments
77
+ program.parse(process.argv);
78
+ // Show help if no command provided
79
+ if (!process.argv.slice(2).length) {
80
+ program.outputHelp();
81
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Client-side helper for handing a local trail off to a running Principal
3
+ * desktop app (electron-app) over its MCP bridge HTTP surface.
4
+ *
5
+ * Preferred over the Unix-socket handoff (viewer-ipc.ts) when the desktop app
6
+ * is running: the bridge's `POST /api/file-city/trail/activate` route reads the
7
+ * same on-disk trail store the app persists to, so a *local* trail id resolves
8
+ * and opens in the app without a network fetch or GitHub token. Returns false
9
+ * (caller falls back to the standalone viewer) when the app isn't running, the
10
+ * probe times out, or the app doesn't have that trail.
11
+ *
12
+ * Duplicated rather than shared because cli and electron-app are independent
13
+ * packages in separate repos — the HTTP route is the contract, this module
14
+ * speaks it from the producer side.
15
+ */
16
+ /**
17
+ * Ask a running desktop app to open `trailId` from its local store. Returns
18
+ * true only when the app actually surfaced the trail — i.e. it found the id AND
19
+ * opened/focused a window (or broadcast the payload to an open one). A 404 (app
20
+ * running but trail not in its store) or a no-window result returns false so the
21
+ * caller can fall back to the standalone viewer.
22
+ */
23
+ export declare function handoffToBridge(trailId: string): Promise<boolean>;
24
+ /**
25
+ * Ask a running desktop app to open `topicId` from its local store. Mirrors
26
+ * `handoffToBridge` but targets the topic activate route.
27
+ */
28
+ export declare function handoffTopicToBridge(topicId: string): Promise<boolean>;
29
+ //# sourceMappingURL=bridge-ipc.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bridge-ipc.d.ts","sourceRoot":"","sources":["../../src/lib/bridge-ipc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwDH;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA4BvE;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA0B5E"}
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Client-side helper for handing a local trail off to a running Principal
3
+ * desktop app (electron-app) over its MCP bridge HTTP surface.
4
+ *
5
+ * Preferred over the Unix-socket handoff (viewer-ipc.ts) when the desktop app
6
+ * is running: the bridge's `POST /api/file-city/trail/activate` route reads the
7
+ * same on-disk trail store the app persists to, so a *local* trail id resolves
8
+ * and opens in the app without a network fetch or GitHub token. Returns false
9
+ * (caller falls back to the standalone viewer) when the app isn't running, the
10
+ * probe times out, or the app doesn't have that trail.
11
+ *
12
+ * Duplicated rather than shared because cli and electron-app are independent
13
+ * packages in separate repos — the HTTP route is the contract, this module
14
+ * speaks it from the producer side.
15
+ */
16
+ // Default port the electron-app's PrincipalMCPBridge binds. Overridable for dev
17
+ // builds / tests via PRINCIPAL_BRIDGE_PORT.
18
+ function bridgePort() {
19
+ const raw = process.env['PRINCIPAL_BRIDGE_PORT'];
20
+ const parsed = raw ? Number.parseInt(raw, 10) : NaN;
21
+ return Number.isInteger(parsed) && parsed > 0 ? parsed : 3044;
22
+ }
23
+ // Candidate hosts, in order. The app binds loopback but may be IPv6-only
24
+ // (`::1`) or IPv4-only (`127.0.0.1`) depending on the OS, and `localhost`
25
+ // resolution order varies by machine — so we probe each rather than trusting a
26
+ // single spelling. PRINCIPAL_BRIDGE_HOST pins one explicitly when needed.
27
+ function bridgeHosts() {
28
+ const override = process.env['PRINCIPAL_BRIDGE_HOST'];
29
+ if (override)
30
+ return [override];
31
+ return ['localhost', '127.0.0.1', '[::1]'];
32
+ }
33
+ function bridgeBases() {
34
+ const port = bridgePort();
35
+ return bridgeHosts().map((host) => `http://${host}:${port}`);
36
+ }
37
+ // Kept short: when the app isn't running we want to fall through to the
38
+ // socket/spawn path fast.
39
+ const PROBE_TIMEOUT_MS = 300;
40
+ // The activate call opens/focuses a window; allow a little more headroom.
41
+ const ACTIVATE_TIMEOUT_MS = 2_000;
42
+ /**
43
+ * Probe the candidate bases and return the first that answers /health, so the
44
+ * follow-up activate call reuses the exact host that worked. Returns null when
45
+ * none respond (app not running).
46
+ */
47
+ async function reachableBase() {
48
+ for (const base of bridgeBases()) {
49
+ try {
50
+ const res = await fetch(`${base}/health`, {
51
+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
52
+ });
53
+ if (res.ok)
54
+ return base;
55
+ }
56
+ catch {
57
+ // try the next host
58
+ }
59
+ }
60
+ return null;
61
+ }
62
+ /**
63
+ * Ask a running desktop app to open `trailId` from its local store. Returns
64
+ * true only when the app actually surfaced the trail — i.e. it found the id AND
65
+ * opened/focused a window (or broadcast the payload to an open one). A 404 (app
66
+ * running but trail not in its store) or a no-window result returns false so the
67
+ * caller can fall back to the standalone viewer.
68
+ */
69
+ export async function handoffToBridge(trailId) {
70
+ const base = await reachableBase();
71
+ if (!base)
72
+ return false;
73
+ let res;
74
+ try {
75
+ res = await fetch(`${base}/api/file-city/trail/activate`, {
76
+ method: 'POST',
77
+ headers: { 'Content-Type': 'application/json' },
78
+ body: JSON.stringify({ id: trailId }),
79
+ signal: AbortSignal.timeout(ACTIVATE_TIMEOUT_MS),
80
+ });
81
+ }
82
+ catch {
83
+ return false;
84
+ }
85
+ if (!res.ok)
86
+ return false;
87
+ let data;
88
+ try {
89
+ data = (await res.json());
90
+ }
91
+ catch {
92
+ return false;
93
+ }
94
+ const surfaced = (data.windowOpened !== undefined && data.windowOpened !== 'none') ||
95
+ (typeof data.broadcastTo === 'number' && data.broadcastTo > 0);
96
+ return data.success === true && surfaced;
97
+ }
98
+ /**
99
+ * Ask a running desktop app to open `topicId` from its local store. Mirrors
100
+ * `handoffToBridge` but targets the topic activate route.
101
+ */
102
+ export async function handoffTopicToBridge(topicId) {
103
+ const base = await reachableBase();
104
+ if (!base)
105
+ return false;
106
+ let res;
107
+ try {
108
+ res = await fetch(`${base}/api/topics/${encodeURIComponent(topicId)}/activate`, {
109
+ method: 'POST',
110
+ signal: AbortSignal.timeout(ACTIVATE_TIMEOUT_MS),
111
+ });
112
+ }
113
+ catch {
114
+ return false;
115
+ }
116
+ if (!res.ok)
117
+ return false;
118
+ let data;
119
+ try {
120
+ data = (await res.json());
121
+ }
122
+ catch {
123
+ return false;
124
+ }
125
+ const surfaced = (data.windowOpened !== undefined && data.windowOpened !== 'none') ||
126
+ (typeof data.delivered === 'number' && data.delivered > 0);
127
+ return data.success === true && surfaced;
128
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * GitHub user lookup helpers shared by web-ade-facing CLI commands.
3
+ *
4
+ * Both `trail list` and `topic list` accept `--user <login>` or default to
5
+ * "the authenticated user." Login → numeric id resolution and the bare-/me/
6
+ * lookup both go through the public GitHub API with the same token chain
7
+ * the rest of the CLI already uses (gh CLI → git credential helper). These
8
+ * lookups are pure HTTP — no SDK dependency, no state — and identical
9
+ * across commands, so they live here once.
10
+ */
11
+ export interface GitHubUserId {
12
+ id: number;
13
+ login: string;
14
+ }
15
+ export declare function fetchGitHubMe(token: string): Promise<GitHubUserId>;
16
+ export declare function fetchGitHubUserByLogin(login: string, token: string): Promise<GitHubUserId>;
17
+ //# sourceMappingURL=github-user.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"github-user.d.ts","sourceRoot":"","sources":["../../src/lib/github-user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkBxE;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CA2BvB"}
@@ -0,0 +1,53 @@
1
+ /**
2
+ * GitHub user lookup helpers shared by web-ade-facing CLI commands.
3
+ *
4
+ * Both `trail list` and `topic list` accept `--user <login>` or default to
5
+ * "the authenticated user." Login → numeric id resolution and the bare-/me/
6
+ * lookup both go through the public GitHub API with the same token chain
7
+ * the rest of the CLI already uses (gh CLI → git credential helper). These
8
+ * lookups are pure HTTP — no SDK dependency, no state — and identical
9
+ * across commands, so they live here once.
10
+ */
11
+ const GITHUB_API = 'https://api.github.com';
12
+ export async function fetchGitHubMe(token) {
13
+ const response = await fetch(`${GITHUB_API}/user`, {
14
+ headers: {
15
+ Authorization: `Bearer ${token}`,
16
+ Accept: 'application/vnd.github+json',
17
+ 'User-Agent': 'principal-ai-cli',
18
+ },
19
+ });
20
+ if (!response.ok) {
21
+ process.stderr.write(`GitHub /user failed: HTTP ${response.status}\n`);
22
+ process.exit(1);
23
+ }
24
+ const body = (await response.json());
25
+ if (typeof body.id !== 'number' || typeof body.login !== 'string') {
26
+ process.stderr.write('GitHub /user returned an unexpected shape\n');
27
+ process.exit(1);
28
+ }
29
+ return { id: body.id, login: body.login };
30
+ }
31
+ export async function fetchGitHubUserByLogin(login, token) {
32
+ const response = await fetch(`${GITHUB_API}/users/${encodeURIComponent(login)}`, {
33
+ headers: {
34
+ Authorization: `Bearer ${token}`,
35
+ Accept: 'application/vnd.github+json',
36
+ 'User-Agent': 'principal-ai-cli',
37
+ },
38
+ });
39
+ if (response.status === 404) {
40
+ process.stderr.write(`GitHub user not found: ${login}\n`);
41
+ process.exit(1);
42
+ }
43
+ if (!response.ok) {
44
+ process.stderr.write(`GitHub /users/${login} failed: HTTP ${response.status}\n`);
45
+ process.exit(1);
46
+ }
47
+ const body = (await response.json());
48
+ if (typeof body.id !== 'number' || typeof body.login !== 'string') {
49
+ process.stderr.write('GitHub /users returned an unexpected shape\n');
50
+ process.exit(1);
51
+ }
52
+ return { id: body.id, login: body.login };
53
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Cross-platform "open this URL in the default browser" helper.
3
+ *
4
+ * Used by `topic open` and `trail open-web`. Detaches + unrefs the child so
5
+ * the CLI returns immediately rather than waiting on the browser process.
6
+ * Headless machines (CI, ssh sessions) will see a friendly stderr warning;
7
+ * the URL itself is still printed to stdout by the caller, so the user can
8
+ * always copy it.
9
+ */
10
+ export declare function openInBrowser(url: string): void;
11
+ //# sourceMappingURL=open-url.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"open-url.d.ts","sourceRoot":"","sources":["../../src/lib/open-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAuC/C"}
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Cross-platform "open this URL in the default browser" helper.
3
+ *
4
+ * Used by `topic open` and `trail open-web`. Detaches + unrefs the child so
5
+ * the CLI returns immediately rather than waiting on the browser process.
6
+ * Headless machines (CI, ssh sessions) will see a friendly stderr warning;
7
+ * the URL itself is still printed to stdout by the caller, so the user can
8
+ * always copy it.
9
+ */
10
+ import { spawn } from 'node:child_process';
11
+ export function openInBrowser(url) {
12
+ let cmd;
13
+ let args;
14
+ switch (process.platform) {
15
+ case 'darwin':
16
+ cmd = 'open';
17
+ args = [url];
18
+ break;
19
+ case 'win32':
20
+ // `start` is a cmd builtin; the empty quoted string is the window title
21
+ // slot, which would otherwise eat the URL on some shells.
22
+ cmd = 'cmd';
23
+ args = ['/c', 'start', '""', url];
24
+ break;
25
+ default:
26
+ cmd = 'xdg-open';
27
+ args = [url];
28
+ break;
29
+ }
30
+ try {
31
+ const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
32
+ child.on('error', (err) => {
33
+ if (err.code === 'ENOENT') {
34
+ process.stderr.write(`Could not auto-open the browser (no \`${cmd}\` on PATH). The URL is printed above.\n`);
35
+ }
36
+ else {
37
+ process.stderr.write(`Could not auto-open the browser: ${err.message}\n`);
38
+ }
39
+ });
40
+ child.unref();
41
+ }
42
+ catch (err) {
43
+ process.stderr.write(`Could not auto-open the browser: ${err.message}\n`);
44
+ }
45
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Local subsystem-model store — same on-disk layout as Principal Studio:
3
+ * `~/.principal/subsystem-models/<id>.json` + `_index.json`.
4
+ *
5
+ * Lets the CLI create/list models without Studio's HTTP bridge running.
6
+ * Structural validation mirrors the Studio POST gate (construct / mechanism /
7
+ * throughlines / detail provenance). File/symbol verification is Studio-only
8
+ * for now and may be empty on CLI-created records until opened/updated there.
9
+ */
10
+ export declare const SUBSYSTEM_EDGE_MECHANISMS: readonly ["imports", "imports_from", "re_exports", "defines", "calls", "extends", "inherits", "implements", "mixes_in", "uses", "method", "references", "contains", "feeds", "produces", "writes", "reads", "watches", "registers-into"];
11
+ export declare const SUBSYSTEM_COMPONENT_CONSTRUCTS: readonly ["class", "function", "method", "interface", "type_alias", "enum", "store", "external"];
12
+ export declare const SUBSYSTEM_DETAIL_PROVENANCES: readonly ["verified", "authored"];
13
+ export interface SubsystemModelIndexEntry {
14
+ id: string;
15
+ title: string;
16
+ description?: string;
17
+ componentCount: number;
18
+ edgeCount: number;
19
+ createdAt: string;
20
+ updatedAt: string;
21
+ lastOpenedAt?: string;
22
+ fileName: string;
23
+ source?: string;
24
+ repo?: {
25
+ owner: string;
26
+ name: string;
27
+ };
28
+ }
29
+ export interface StoredSubsystemModel {
30
+ id: string;
31
+ title: string;
32
+ description?: string;
33
+ components: unknown[];
34
+ edges: unknown[];
35
+ throughlines?: unknown[];
36
+ createdAt: string;
37
+ updatedAt: string;
38
+ lastOpenedAt?: string;
39
+ source?: string;
40
+ repo?: {
41
+ owner: string;
42
+ name: string;
43
+ };
44
+ repoRoot?: string;
45
+ repoRoots?: Record<string, string>;
46
+ verification?: unknown;
47
+ }
48
+ export interface CreateSubsystemModelInput {
49
+ title: string;
50
+ description?: string;
51
+ components: unknown[];
52
+ edges: unknown[];
53
+ throughlines?: unknown[];
54
+ source?: string;
55
+ repo?: {
56
+ owner: string;
57
+ name: string;
58
+ };
59
+ repoRoot?: string;
60
+ repoRoots?: Record<string, string>;
61
+ }
62
+ export declare function subsystemModelFilePath(id: string): string;
63
+ export declare function findEdgeMechanismProblems(edges: unknown): string[];
64
+ export declare function findThroughlineProblems(edges: unknown, throughlines: unknown): string[];
65
+ export declare function findComponentConstructProblems(components: unknown): string[];
66
+ export declare function findDetailProvenanceProblems(components: unknown): string[];
67
+ export declare function normalizeDetailProvenance(components: unknown): void;
68
+ export declare function isRepoRoots(value: unknown): value is Record<string, string>;
69
+ /** Structural problems that would make Studio reject a POST (empty = valid). */
70
+ export declare function findCreateProblems(body: Record<string, unknown>): string[];
71
+ export declare function listSubsystemModels(): Promise<SubsystemModelIndexEntry[]>;
72
+ export declare function getSubsystemModel(id: string): Promise<StoredSubsystemModel | null>;
73
+ export declare function createSubsystemModel(doc: CreateSubsystemModelInput): Promise<StoredSubsystemModel>;
74
+ //# sourceMappingURL=subsystem-model-store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"subsystem-model-store.d.ts","sourceRoot":"","sources":["../../src/lib/subsystem-model-store.ts"],"names":[],"mappings":"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"}