@picassohq/cli 0.0.0-stage → 1.0.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 (232) hide show
  1. package/agents/browser_agent.yaml +53 -0
  2. package/agents/code_reviewer.yaml +49 -0
  3. package/agents/codebase_investigator.yaml +70 -0
  4. package/agents/design_auditor.yaml +50 -0
  5. package/agents/devex_auditor.yaml +50 -0
  6. package/agents/doc_writer.yaml +54 -0
  7. package/agents/engineering_architect.yaml +51 -0
  8. package/agents/generalist.yaml +55 -0
  9. package/agents/migration_planner.yaml +51 -0
  10. package/agents/product_reviewer.yaml +48 -0
  11. package/agents/qa_operator.yaml +52 -0
  12. package/agents/release_engineer.yaml +50 -0
  13. package/agents/security_auditor.yaml +62 -0
  14. package/agents/test_writer.yaml +52 -0
  15. package/assets/first-light-lockup.png +0 -0
  16. package/assets/first-light-tagline.png +0 -0
  17. package/assets/house/README.md +26 -0
  18. package/assets/house/auraone-banner.png +0 -0
  19. package/assets/house/auraone-logo.png +0 -0
  20. package/assets/house/kiro-prism-banner.png +0 -0
  21. package/assets/house/kiro-prism-logo.png +0 -0
  22. package/assets/house/picasso-banner.png +0 -0
  23. package/assets/house/picasso-logo.png +0 -0
  24. package/assets/wordmark-app.png +0 -0
  25. package/assets/wordmark-tight.png +0 -0
  26. package/assets/wordmark.png +0 -0
  27. package/design/styles.css +1042 -0
  28. package/dist/build-info.json +37 -0
  29. package/dist/index.js +3062 -0
  30. package/goals/cli-hardening.yaml +40 -0
  31. package/goals/repo-maintenance.yaml +40 -0
  32. package/package.json +49 -4
  33. package/runtime/dsh/picasso-ecosystem.community.amendments.yml +24 -0
  34. package/runtime/dsh/picasso-ecosystem.community.json +185 -0
  35. package/runtime/dsh/picasso-ecosystem.community.patch.yml +40 -0
  36. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +143 -0
  37. package/runtime/dsh/picasso-isolation.patch.yml +25 -0
  38. package/runtime/dsh/picasso-providers.patch.yml +373 -0
  39. package/runtime/dsh/picasso-runtime.cordis.yml +738 -0
  40. package/runtime/dsh/picasso-sdk.patch.yml +204 -0
  41. package/runtime/engine-manifest.json +215 -0
  42. package/runtime/package.json +6 -0
  43. package/runtime/packages/picasso-cache-probe/cordis.patch.yml +5 -0
  44. package/runtime/packages/picasso-cache-probe/index.js +477 -0
  45. package/runtime/packages/picasso-cache-probe/package.json +38 -0
  46. package/runtime/packages/picasso-commands/cordis.patch.yml +4 -0
  47. package/runtime/packages/picasso-commands/fresh-review.js +573 -0
  48. package/runtime/packages/picasso-commands/index.js +497 -0
  49. package/runtime/packages/picasso-commands/package.json +28 -0
  50. package/runtime/packages/picasso-instructions/conflicts.js +115 -0
  51. package/runtime/packages/picasso-instructions/formats.js +145 -0
  52. package/runtime/packages/picasso-instructions/frontmatter.js +175 -0
  53. package/runtime/packages/picasso-instructions/glob.js +114 -0
  54. package/runtime/packages/picasso-instructions/globals.js +90 -0
  55. package/runtime/packages/picasso-instructions/imports.js +123 -0
  56. package/runtime/packages/picasso-instructions/index.js +326 -0
  57. package/runtime/packages/picasso-instructions/modes.js +64 -0
  58. package/runtime/packages/picasso-instructions/package.json +30 -0
  59. package/runtime/packages/picasso-instructions/parse.js +134 -0
  60. package/runtime/packages/picasso-instructions/report.js +161 -0
  61. package/runtime/packages/picasso-instructions/resolve.js +939 -0
  62. package/runtime/packages/picasso-instructions/scan.js +181 -0
  63. package/runtime/packages/picasso-instructions/settings.js +150 -0
  64. package/runtime/packages/picasso-instructions/skills.js +345 -0
  65. package/runtime/packages/picasso-lean-context/cordis.patch.yml +13 -0
  66. package/runtime/packages/picasso-lean-context/index.js +6280 -0
  67. package/runtime/packages/picasso-lean-context/package.json +26 -0
  68. package/runtime/packages/picasso-lean-context/read-image-recovery.js +306 -0
  69. package/runtime/packages/picasso-lean-context/timeline.js +418 -0
  70. package/runtime/packages/picasso-librarian/classify.js +146 -0
  71. package/runtime/packages/picasso-librarian/cordis.patch.yml +10 -0
  72. package/runtime/packages/picasso-librarian/index.js +878 -0
  73. package/runtime/packages/picasso-librarian/notes.js +159 -0
  74. package/runtime/packages/picasso-librarian/package.json +34 -0
  75. package/runtime/packages/picasso-librarian/state.js +478 -0
  76. package/runtime/packages/picasso-memory/index.js +1184 -0
  77. package/runtime/packages/picasso-memory/package.json +21 -0
  78. package/runtime/packages/picasso-model-router/connections.js +912 -0
  79. package/runtime/packages/picasso-model-router/cordis.patch.yml +17 -0
  80. package/runtime/packages/picasso-model-router/index.js +1083 -0
  81. package/runtime/packages/picasso-model-router/package.json +30 -0
  82. package/runtime/packages/picasso-options/cordis.patch.yml +4 -0
  83. package/runtime/packages/picasso-options/index.js +263 -0
  84. package/runtime/packages/picasso-options/package.json +28 -0
  85. package/runtime/packages/picasso-progress-reports/cordis.patch.yml +10 -0
  86. package/runtime/packages/picasso-progress-reports/index.js +267 -0
  87. package/runtime/packages/picasso-progress-reports/package.json +30 -0
  88. package/runtime/packages/picasso-progress-reports/report.js +235 -0
  89. package/runtime/packages/picasso-sdk-server/aside.js +142 -0
  90. package/runtime/packages/picasso-sdk-server/connections.js +38 -0
  91. package/runtime/packages/picasso-sdk-server/context-timeline.js +27 -0
  92. package/runtime/packages/picasso-sdk-server/egress-gate.js +520 -0
  93. package/runtime/packages/picasso-sdk-server/failure-policy.js +246 -0
  94. package/runtime/packages/picasso-sdk-server/file-input.js +169 -0
  95. package/runtime/packages/picasso-sdk-server/goal.js +131 -0
  96. package/runtime/packages/picasso-sdk-server/ignore-file.js +458 -0
  97. package/runtime/packages/picasso-sdk-server/ignore-plugin.js +12 -0
  98. package/runtime/packages/picasso-sdk-server/ignore-sandbox.js +122 -0
  99. package/runtime/packages/picasso-sdk-server/ignore-snapshot.js +131 -0
  100. package/runtime/packages/picasso-sdk-server/image-input.js +44 -0
  101. package/runtime/packages/picasso-sdk-server/index.js +891 -0
  102. package/runtime/packages/picasso-sdk-server/instructions.js +34 -0
  103. package/runtime/packages/picasso-sdk-server/jobs.js +113 -0
  104. package/runtime/packages/picasso-sdk-server/mcp-gate.js +51 -0
  105. package/runtime/packages/picasso-sdk-server/model-selection.js +162 -0
  106. package/runtime/packages/picasso-sdk-server/package.json +50 -0
  107. package/runtime/packages/picasso-sdk-server/picasso-records.js +50 -0
  108. package/runtime/packages/picasso-sdk-server/provider-reload.js +84 -0
  109. package/runtime/packages/picasso-sdk-server/queue.js +322 -0
  110. package/runtime/packages/picasso-sdk-server/requester.js +43 -0
  111. package/runtime/packages/picasso-sdk-server/rewind.js +108 -0
  112. package/runtime/packages/picasso-sdk-server/schedule.js +187 -0
  113. package/runtime/packages/picasso-sdk-server/session-grants.js +35 -0
  114. package/runtime/packages/picasso-sdk-server/session-state.js +118 -0
  115. package/runtime/packages/picasso-sdk-server/shell-paths.js +869 -0
  116. package/runtime/packages/picasso-sdk-server/stream-deltas.js +211 -0
  117. package/runtime/packages/picasso-sdk-server/team-tasks.js +451 -0
  118. package/runtime/packages/picasso-sdk-server/tool-output.js +128 -0
  119. package/runtime/packages/picasso-sdk-server/tools-list.js +51 -0
  120. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +612 -0
  121. package/runtime/packages/picasso-sdk-server/workspace-archive.js +170 -0
  122. package/runtime/packages/picasso-sdk-server/workspace-restore.js +180 -0
  123. package/runtime/packages/picasso-web-search/backends.js +412 -0
  124. package/runtime/packages/picasso-web-search/config.js +121 -0
  125. package/runtime/packages/picasso-web-search/cordis.patch.yml +7 -0
  126. package/runtime/packages/picasso-web-search/failure.js +116 -0
  127. package/runtime/packages/picasso-web-search/format.js +42 -0
  128. package/runtime/packages/picasso-web-search/index.js +71 -0
  129. package/runtime/packages/picasso-web-search/package.json +38 -0
  130. package/runtime/packages/picasso-web-search/router.js +156 -0
  131. package/runtime/packages/picasso-x-reader/circle.js +324 -0
  132. package/runtime/packages/picasso-x-reader/command.js +169 -0
  133. package/runtime/packages/picasso-x-reader/cordis.patch.yml +8 -0
  134. package/runtime/packages/picasso-x-reader/index.js +170 -0
  135. package/runtime/packages/picasso-x-reader/package.json +39 -0
  136. package/runtime/packages/picasso-x-reader/read.js +370 -0
  137. package/runtime/packages/picasso-x-reader/rewrite.js +38 -0
  138. package/runtime/packages/picasso-x-reader/settings.js +131 -0
  139. package/runtime/packages/picasso-x-reader/urls.js +154 -0
  140. package/runtime/packages/picasso-x-reader/xmd.js +512 -0
  141. package/runtime/plugins/picasso-auth-bridge/index.js +380 -0
  142. package/runtime/plugins/picasso-auth-bridge/package.json +28 -0
  143. package/runtime/plugins/picasso-auto-approve/index.js +1003 -0
  144. package/runtime/plugins/picasso-auto-approve/package.json +28 -0
  145. package/runtime/plugins/picasso-browser/index.js +424 -0
  146. package/runtime/plugins/picasso-browser/package.json +28 -0
  147. package/runtime/plugins/picasso-checkpoints/evidence.js +210 -0
  148. package/runtime/plugins/picasso-checkpoints/index.js +885 -0
  149. package/runtime/plugins/picasso-checkpoints/package.json +29 -0
  150. package/runtime/plugins/picasso-commands/fresh-review.js +573 -0
  151. package/runtime/plugins/picasso-commands/index.js +497 -0
  152. package/runtime/plugins/picasso-commands/package.json +28 -0
  153. package/runtime/plugins/picasso-instructions/conflicts.js +115 -0
  154. package/runtime/plugins/picasso-instructions/formats.js +145 -0
  155. package/runtime/plugins/picasso-instructions/frontmatter.js +175 -0
  156. package/runtime/plugins/picasso-instructions/glob.js +114 -0
  157. package/runtime/plugins/picasso-instructions/globals.js +90 -0
  158. package/runtime/plugins/picasso-instructions/imports.js +123 -0
  159. package/runtime/plugins/picasso-instructions/index.js +326 -0
  160. package/runtime/plugins/picasso-instructions/modes.js +64 -0
  161. package/runtime/plugins/picasso-instructions/package.json +30 -0
  162. package/runtime/plugins/picasso-instructions/parse.js +134 -0
  163. package/runtime/plugins/picasso-instructions/report.js +161 -0
  164. package/runtime/plugins/picasso-instructions/resolve.js +939 -0
  165. package/runtime/plugins/picasso-instructions/scan.js +181 -0
  166. package/runtime/plugins/picasso-instructions/settings.js +150 -0
  167. package/runtime/plugins/picasso-instructions/skills.js +345 -0
  168. package/runtime/plugins/picasso-lean-context/index.js +6280 -0
  169. package/runtime/plugins/picasso-lean-context/package.json +26 -0
  170. package/runtime/plugins/picasso-lean-context/read-image-recovery.js +306 -0
  171. package/runtime/plugins/picasso-lean-context/timeline.js +418 -0
  172. package/runtime/plugins/picasso-librarian/classify.js +146 -0
  173. package/runtime/plugins/picasso-librarian/index.js +878 -0
  174. package/runtime/plugins/picasso-librarian/notes.js +159 -0
  175. package/runtime/plugins/picasso-librarian/package.json +34 -0
  176. package/runtime/plugins/picasso-librarian/state.js +478 -0
  177. package/runtime/plugins/picasso-lifecycle-hooks/index.js +186 -0
  178. package/runtime/plugins/picasso-lifecycle-hooks/package.json +25 -0
  179. package/runtime/plugins/picasso-mail/inbox.js +207 -0
  180. package/runtime/plugins/picasso-mail/index.js +293 -0
  181. package/runtime/plugins/picasso-mail/package.json +22 -0
  182. package/runtime/plugins/picasso-memory/index.js +1184 -0
  183. package/runtime/plugins/picasso-memory/package.json +21 -0
  184. package/runtime/plugins/picasso-model-router/connections.js +912 -0
  185. package/runtime/plugins/picasso-model-router/index.js +1083 -0
  186. package/runtime/plugins/picasso-model-router/package.json +30 -0
  187. package/runtime/plugins/picasso-options/index.js +263 -0
  188. package/runtime/plugins/picasso-options/package.json +28 -0
  189. package/runtime/plugins/picasso-progress-reports/index.js +267 -0
  190. package/runtime/plugins/picasso-progress-reports/package.json +30 -0
  191. package/runtime/plugins/picasso-progress-reports/report.js +235 -0
  192. package/runtime/plugins/picasso-provider-models/index.js +436 -0
  193. package/runtime/plugins/picasso-provider-models/package.json +28 -0
  194. package/runtime/plugins/picasso-repo-index/index.js +1850 -0
  195. package/runtime/plugins/picasso-repo-index/package.json +28 -0
  196. package/runtime/plugins/picasso-schedule-pause/index.js +344 -0
  197. package/runtime/plugins/picasso-schedule-pause/package.json +28 -0
  198. package/runtime/plugins/picasso-session-lifecycle/index.js +796 -0
  199. package/runtime/plugins/picasso-session-lifecycle/package.json +28 -0
  200. package/runtime/plugins/picasso-trackers/index.js +895 -0
  201. package/runtime/plugins/picasso-trackers/package.json +28 -0
  202. package/runtime/plugins/picasso-web-search/backends.js +412 -0
  203. package/runtime/plugins/picasso-web-search/config.js +121 -0
  204. package/runtime/plugins/picasso-web-search/failure.js +116 -0
  205. package/runtime/plugins/picasso-web-search/format.js +42 -0
  206. package/runtime/plugins/picasso-web-search/index.js +71 -0
  207. package/runtime/plugins/picasso-web-search/package.json +38 -0
  208. package/runtime/plugins/picasso-web-search/router.js +156 -0
  209. package/runtime/plugins/picasso-x-reader/circle.js +324 -0
  210. package/runtime/plugins/picasso-x-reader/command.js +169 -0
  211. package/runtime/plugins/picasso-x-reader/index.js +170 -0
  212. package/runtime/plugins/picasso-x-reader/package.json +39 -0
  213. package/runtime/plugins/picasso-x-reader/read.js +370 -0
  214. package/runtime/plugins/picasso-x-reader/rewrite.js +38 -0
  215. package/runtime/plugins/picasso-x-reader/settings.js +131 -0
  216. package/runtime/plugins/picasso-x-reader/urls.js +154 -0
  217. package/runtime/plugins/picasso-x-reader/xmd.js +512 -0
  218. package/runtime/relay/attachment-text.mjs +737 -0
  219. package/runtime/relay/companion/companion.css +126 -0
  220. package/runtime/relay/companion/companion.js +648 -0
  221. package/runtime/relay/companion/icon.svg +5 -0
  222. package/runtime/relay/companion/index.html +25 -0
  223. package/runtime/relay/companion/manifest.json +13 -0
  224. package/runtime/relay/companion/sw.js +41 -0
  225. package/runtime/relay/main.mjs +38580 -0
  226. package/runtime/relay/model-listing.mjs +614 -0
  227. package/runtime/relay/versions-routes.mjs +1400 -0
  228. package/runtime/verify-plugins.mjs +205 -0
  229. package/runtime-lock/package-lock.json +10779 -0
  230. package/runtime-lock/package.json +7 -0
  231. package/scripts/install-runtime.mjs +400 -0
  232. package/README.md +0 -3
@@ -0,0 +1,145 @@
1
+ // The instruction-format registry: every repository instruction file Picasso recognises (owner spec §1 and §2),
2
+ // the project docs it indexes but never injects (§6), and how each one activates.
3
+ //
4
+ // This table is Picasso's compatibility list, not a claim that each vendor reads every one of these files. The order
5
+ // of FORMATS is the documented cross-vendor precedence inside one directory: Picasso's own file, then the portable
6
+ // AGENTS.md family, then each vendor's repo-wide file, then rule folders. Earlier rows render first (broader), later
7
+ // rows render after them, so a vendor rule refines AGENTS.md and never the other way round.
8
+ //
9
+ // Zero dependencies: the relay ships this file as a top-level module of the plugin directory.
10
+
11
+ /**
12
+ * @typedef {'always' | 'glob' | 'model' | 'manual' | 'index' | 'recognized'} ActivationKind
13
+ *
14
+ * @typedef {object} InstructionFormat
15
+ * @property {string} id stable format id (`agents-md`, `cursor-rules`, …)
16
+ * @property {string} label what the inspector shows
17
+ * @property {string} ecosystem tools that read it
18
+ * @property {'core' | 'additional' | 'docs'} tier spec section: §1 core, §2 additional, §6 docs
19
+ * @property {'file' | 'dir'} shape a single file, or a folder of rule files
20
+ * @property {string} path directory-relative path (file) or folder (dir)
21
+ * @property {RegExp} [match] dir shape: which files inside the folder are rules (relative posix path)
22
+ * @property {boolean} [hierarchical] file shape: also read in every directory between the root and the work (nested)
23
+ * @property {boolean} [frontmatter] parse YAML frontmatter for activation keys
24
+ * @property {ActivationKind} activation default activation when the frontmatter says nothing
25
+ * @property {string} [family] formats in one family are alternatives (`agents-md` vs its override)
26
+ * @property {string} [note] why this format is handled specially (shown in the inspector)
27
+ * @property {string} [modeFromDir] dir shape: a regex source; group 1 of the folder name is the rule's mode
28
+ */
29
+
30
+ /** @type {readonly InstructionFormat[]} */
31
+ export const FORMATS = Object.freeze([
32
+ // ---- Picasso's own and the portable AGENTS.md family (§1) ----
33
+ { id: 'picasso-md', label: 'PICASSO.md', ecosystem: 'Picasso', tier: 'core', shape: 'file', path: 'PICASSO.md', hierarchical: true, activation: 'always' },
34
+ {
35
+ id: 'agents-override-md', label: 'AGENTS.override.md', ecosystem: 'Codex', tier: 'core', shape: 'file', path: 'AGENTS.override.md',
36
+ hierarchical: true, activation: 'always', family: 'agents-md', note: 'Replaces AGENTS.md in its own directory (Codex semantics).',
37
+ },
38
+ { id: 'agents-md', label: 'AGENTS.md', ecosystem: 'Codex, OpenCode, Cursor, Copilot, Amp, others', tier: 'core', shape: 'file', path: 'AGENTS.md', hierarchical: true, activation: 'always', family: 'agents-md' },
39
+ { id: 'agent-md', label: 'AGENT.md', ecosystem: 'Amp, Zed, Devin, Kilo', tier: 'additional', shape: 'file', path: 'AGENT.md', hierarchical: true, activation: 'always' },
40
+ { id: 'agents-local-md', label: 'AGENTS.local.md', ecosystem: 'Devin (personal overlay)', tier: 'additional', shape: 'file', path: 'AGENTS.local.md', hierarchical: true, activation: 'always' },
41
+
42
+ // ---- Claude Code ----
43
+ { id: 'claude-md', label: 'CLAUDE.md', ecosystem: 'Claude Code, Cursor CLI, Copilot CLI', tier: 'core', shape: 'file', path: 'CLAUDE.md', hierarchical: true, activation: 'always' },
44
+ { id: 'claude-dir-md', label: '.claude/CLAUDE.md', ecosystem: 'Claude Code, Copilot CLI', tier: 'core', shape: 'file', path: '.claude/CLAUDE.md', hierarchical: true, activation: 'always' },
45
+ { id: 'claude-local-md', label: 'CLAUDE.local.md', ecosystem: 'Claude Code (personal)', tier: 'core', shape: 'file', path: 'CLAUDE.local.md', hierarchical: true, activation: 'always' },
46
+ { id: 'claude-rules', label: '.claude/rules', ecosystem: 'Claude Code', tier: 'core', shape: 'dir', path: '.claude/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
47
+
48
+ // ---- Gemini CLI, Qwen Code ----
49
+ { id: 'gemini-md', label: 'GEMINI.md', ecosystem: 'Gemini CLI, Copilot CLI', tier: 'core', shape: 'file', path: 'GEMINI.md', hierarchical: true, activation: 'always' },
50
+ { id: 'qwen-md', label: 'QWEN.md', ecosystem: 'Qwen Code', tier: 'additional', shape: 'file', path: 'QWEN.md', hierarchical: true, activation: 'always' },
51
+ { id: 'qwen-local-md', label: '.qwen/QWEN.local.md', ecosystem: 'Qwen Code (personal)', tier: 'additional', shape: 'file', path: '.qwen/QWEN.local.md', activation: 'always' },
52
+
53
+ // ---- GitHub Copilot ----
54
+ { id: 'copilot-instructions', label: '.github/copilot-instructions.md', ecosystem: 'GitHub Copilot', tier: 'core', shape: 'file', path: '.github/copilot-instructions.md', activation: 'always' },
55
+ {
56
+ id: 'copilot-scoped', label: '.github/instructions', ecosystem: 'GitHub Copilot, VS Code', tier: 'core', shape: 'dir', path: '.github/instructions',
57
+ match: /\.instructions\.md$/u, frontmatter: true, activation: 'manual', note: 'applyTo file patterns; a file without applyTo is applied only on request.',
58
+ },
59
+
60
+ // ---- Cursor ----
61
+ { id: 'cursor-rules', label: '.cursor/rules', ecosystem: 'Cursor', tier: 'core', shape: 'dir', path: '.cursor/rules', match: /\.mdc?$/u, frontmatter: true, activation: 'manual' },
62
+ { id: 'cursorrules', label: '.cursorrules', ecosystem: 'Cursor (legacy)', tier: 'core', shape: 'file', path: '.cursorrules', activation: 'always' },
63
+
64
+ // ---- Windsurf ----
65
+ { id: 'windsurf-rules', label: '.windsurf/rules', ecosystem: 'Windsurf', tier: 'core', shape: 'dir', path: '.windsurf/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
66
+ { id: 'windsurfrules', label: '.windsurfrules', ecosystem: 'Windsurf (legacy)', tier: 'core', shape: 'file', path: '.windsurfrules', activation: 'always' },
67
+ { id: 'windsurf-global-rules', label: '.windsurf/global_rules.md', ecosystem: 'Windsurf (legacy)', tier: 'additional', shape: 'file', path: '.windsurf/global_rules.md', activation: 'always' },
68
+
69
+ // ---- Cline, Roo Code ----
70
+ { id: 'clinerules-dir', label: '.clinerules/', ecosystem: 'Cline', tier: 'core', shape: 'dir', path: '.clinerules', match: /\.(?:md|txt)$/u, frontmatter: true, activation: 'always' },
71
+ { id: 'clinerules', label: '.clinerules', ecosystem: 'Cline', tier: 'core', shape: 'file', path: '.clinerules', activation: 'always' },
72
+ { id: 'cline-rules', label: '.cline/rules', ecosystem: 'Cline', tier: 'core', shape: 'dir', path: '.cline/rules', match: /\.(?:md|txt)$/u, frontmatter: true, activation: 'always' },
73
+ { id: 'roo-rules', label: '.roo/rules', ecosystem: 'Roo Code', tier: 'core', shape: 'dir', path: '.roo/rules', match: /\.(?:md|txt)$/u, frontmatter: true, activation: 'always' },
74
+ {
75
+ id: 'roo-mode-rules', label: '.roo/rules-<mode>', ecosystem: 'Roo Code (mode rules)', tier: 'core', shape: 'dir', path: '.roo',
76
+ match: /^rules-[^/]+\/.+\.(?:md|txt)$/u, frontmatter: true, activation: 'manual', modeFromDir: '^rules-([^/]+)/',
77
+ note: 'Mode-specific: applied only when that mode is requested.',
78
+ },
79
+ { id: 'roorules', label: '.roorules', ecosystem: 'Roo Code (legacy)', tier: 'core', shape: 'file', path: '.roorules', activation: 'always' },
80
+
81
+ // ---- Continue, Kiro ----
82
+ { id: 'continue-rules', label: '.continue/rules', ecosystem: 'Continue', tier: 'core', shape: 'dir', path: '.continue/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
83
+ { id: 'kiro-steering', label: '.kiro/steering', ecosystem: 'Kiro', tier: 'core', shape: 'dir', path: '.kiro/steering', match: /\.md$/u, frontmatter: true, activation: 'always' },
84
+
85
+ // ---- Devin, Antigravity ----
86
+ { id: 'devin-global-rules', label: '.devin/global_rules.md', ecosystem: 'Devin', tier: 'additional', shape: 'file', path: '.devin/global_rules.md', activation: 'always' },
87
+ { id: 'devin-rules', label: '.devin/rules', ecosystem: 'Devin', tier: 'additional', shape: 'dir', path: '.devin/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
88
+ { id: 'agents-rules', label: '.agents/rules', ecosystem: 'Google Antigravity', tier: 'additional', shape: 'dir', path: '.agents/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
89
+ { id: 'agent-rules', label: '.agent/rules', ecosystem: 'Google Antigravity (legacy)', tier: 'additional', shape: 'dir', path: '.agent/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
90
+
91
+ // ---- Augment ----
92
+ { id: 'augment-rules', label: '.augment/rules', ecosystem: 'Augment Code', tier: 'additional', shape: 'dir', path: '.augment/rules', match: /\.mdc?$/u, frontmatter: true, activation: 'always' },
93
+ {
94
+ id: 'augment-append-system', label: '.augment/APPEND_SYSTEM.md', ecosystem: 'Augment Code', tier: 'additional', shape: 'file', path: '.augment/APPEND_SYSTEM.md',
95
+ activation: 'always', note: 'Imported as a labelled project instruction, never as a system prompt.',
96
+ },
97
+ {
98
+ id: 'augment-system', label: '.augment/SYSTEM.md', ecosystem: 'Augment Code', tier: 'additional', shape: 'file', path: '.augment/SYSTEM.md',
99
+ activation: 'recognized', note: 'Recognised but not applied: a repository file never replaces Picasso\'s own safety and tool instructions.',
100
+ },
101
+ { id: 'augment-guidelines', label: '.augment-guidelines', ecosystem: 'Augment Code (legacy)', tier: 'additional', shape: 'file', path: '.augment-guidelines', activation: 'always' },
102
+
103
+ // ---- Kilo Code, Zed ----
104
+ { id: 'kilo-rules', label: '.kilo/rules', ecosystem: 'Kilo Code', tier: 'additional', shape: 'dir', path: '.kilo/rules', match: /\.md$/u, frontmatter: true, activation: 'always' },
105
+ { id: 'kilocoderules', label: '.kilocoderules', ecosystem: 'Kilo Code (legacy)', tier: 'additional', shape: 'file', path: '.kilocoderules', activation: 'always' },
106
+ { id: 'context-md', label: 'CONTEXT.md', ecosystem: 'Kilo Code', tier: 'additional', shape: 'file', path: 'CONTEXT.md', activation: 'always' },
107
+ { id: 'zed-rules', label: '.rules', ecosystem: 'Zed (legacy)', tier: 'additional', shape: 'file', path: '.rules', activation: 'always' },
108
+ ]);
109
+
110
+ /**
111
+ * Project docs (§6): indexed, listed by path, never injected as standing instructions. A doc loads only when an
112
+ * instruction file or the task references it (the model reads it like any file).
113
+ * @type {readonly { id: string, label: string, path: string, shape: 'file' | 'dir', match?: RegExp, note?: string }[]}
114
+ */
115
+ export const DOC_FORMATS = Object.freeze([
116
+ { id: 'readme', label: 'README.md', path: 'README.md', shape: 'file' },
117
+ { id: 'contributing', label: 'CONTRIBUTING.md', path: 'CONTRIBUTING.md', shape: 'file' },
118
+ { id: 'architecture', label: 'ARCHITECTURE.md', path: 'ARCHITECTURE.md', shape: 'file' },
119
+ { id: 'design-md', label: 'DESIGN.md', path: 'DESIGN.md', shape: 'file', note: 'Design-system guidance (Factory Droid): context, not general instructions.' },
120
+ { id: 'conventions', label: 'CONVENTIONS.md', path: 'CONVENTIONS.md', shape: 'file' },
121
+ { id: 'security-md', label: 'SECURITY.md', path: 'SECURITY.md', shape: 'file' },
122
+ { id: 'changelog', label: 'CHANGELOG.md', path: 'CHANGELOG.md', shape: 'file' },
123
+ { id: 'todo', label: 'TODO.md', path: 'TODO.md', shape: 'file' },
124
+ { id: 'tasks', label: 'TASKS.md', path: 'TASKS.md', shape: 'file' },
125
+ { id: 'plan', label: 'PLAN.md', path: 'PLAN.md', shape: 'file' },
126
+ { id: 'docs', label: 'docs/', path: 'docs', shape: 'dir', match: /\.md$/u },
127
+ { id: 'adr', label: 'ADR/', path: 'ADR', shape: 'dir', match: /\.md$/u },
128
+ { id: 'docs-adr', label: 'docs/adr/', path: 'docs/adr', shape: 'dir', match: /\.md$/u },
129
+ ]);
130
+
131
+ /** Every activation kind, in the order the inspector groups them. */
132
+ export const ACTIVATIONS = Object.freeze(['always', 'glob', 'model', 'manual', 'index', 'recognized']);
133
+
134
+ const BY_ID = new Map(FORMATS.map((format) => [format.id, format]));
135
+
136
+ /** The registry row for a format id, or undefined. */
137
+ export function formatById(id) {
138
+ return BY_ID.get(id);
139
+ }
140
+
141
+ /** Rank of a format inside one directory (registry order): lower renders first. */
142
+ export function formatRank(id) {
143
+ const index = FORMATS.findIndex((format) => format.id === id);
144
+ return index < 0 ? FORMATS.length : index;
145
+ }
@@ -0,0 +1,175 @@
1
+ // A deliberately small YAML-frontmatter reader for instruction and skill files (zero dependencies).
2
+ //
3
+ // It reads the subset these files use: `key: value` scalars (plain, single- or double-quoted), inline lists
4
+ // (`[a, "b"]`), block lists (`- a`), block scalars (`|`, `>`) and booleans/numbers. Anything it does not understand
5
+ // is kept as a plain string, never evaluated: frontmatter is project data.
6
+
7
+ const FENCE = /^---[ \t]*\r?\n/u;
8
+
9
+ /**
10
+ * Split a document into its frontmatter block and body.
11
+ * @param {string} text
12
+ * @returns {{ data: Record<string, unknown>, body: string, hasFrontmatter: boolean, error?: string }}
13
+ */
14
+ export function parseFrontmatter(text) {
15
+ const source = String(text ?? '').replace(/^\uFEFF/u, '');
16
+ if (!FENCE.test(source)) return { data: {}, body: source, hasFrontmatter: false };
17
+ const afterOpen = source.replace(FENCE, '');
18
+ const close = /^(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/mu.exec(afterOpen);
19
+ if (close === null) return { data: {}, body: source, hasFrontmatter: false, error: 'frontmatter is not closed' };
20
+ const block = afterOpen.slice(0, close.index);
21
+ const body = afterOpen.slice(close.index + close[0].length);
22
+ try {
23
+ return { data: parseYamlSubset(block), body, hasFrontmatter: true };
24
+ } catch (error) {
25
+ return { data: {}, body, hasFrontmatter: true, error: error instanceof Error ? error.message : String(error) };
26
+ }
27
+ }
28
+
29
+ function unquote(value) {
30
+ const trimmed = value.trim();
31
+ if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
32
+ return trimmed.slice(1, -1).replace(/\\(["\\nt])/gu, (_m, ch) => (ch === 'n' ? '\n' : ch === 't' ? '\t' : ch));
33
+ }
34
+ if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1).replaceAll("''", "'");
35
+ return trimmed;
36
+ }
37
+
38
+ function stripComment(value) {
39
+ // A `#` starts a comment only outside quotes and after whitespace.
40
+ let quote = '';
41
+ for (let i = 0; i < value.length; i += 1) {
42
+ const ch = value[i];
43
+ if (quote) {
44
+ if (ch === quote) quote = '';
45
+ continue;
46
+ }
47
+ if (ch === '"' || ch === "'") quote = ch;
48
+ else if (ch === '#' && (i === 0 || /\s/u.test(value[i - 1] ?? ''))) return value.slice(0, i);
49
+ }
50
+ return value;
51
+ }
52
+
53
+ function splitInlineList(inner) {
54
+ const items = [];
55
+ let current = '';
56
+ let quote = '';
57
+ let depth = 0;
58
+ for (const ch of inner) {
59
+ if (quote) {
60
+ current += ch;
61
+ if (ch === quote) quote = '';
62
+ continue;
63
+ }
64
+ if (ch === '"' || ch === "'") {
65
+ quote = ch;
66
+ current += ch;
67
+ continue;
68
+ }
69
+ if (ch === '{' || ch === '[') depth += 1;
70
+ if (ch === '}' || ch === ']') depth -= 1;
71
+ if (ch === ',' && depth === 0) {
72
+ items.push(current);
73
+ current = '';
74
+ continue;
75
+ }
76
+ current += ch;
77
+ }
78
+ if (current.trim().length > 0) items.push(current);
79
+ return items.map((item) => scalar(item)).filter((item) => item !== '');
80
+ }
81
+
82
+ /** One scalar: quoted string, inline list, boolean, null, number, or plain string. */
83
+ function scalar(raw) {
84
+ const value = stripComment(raw).trim();
85
+ if (value.startsWith('[') && value.endsWith(']')) return splitInlineList(value.slice(1, -1));
86
+ if (value.startsWith('"') || value.startsWith("'")) return unquote(value);
87
+ if (/^(?:true|yes|on)$/iu.test(value)) return true;
88
+ if (/^(?:false|no|off)$/iu.test(value)) return false;
89
+ if (/^(?:null|~)$/iu.test(value) || value === '') return value === '' ? '' : null;
90
+ if (/^-?\d+(?:\.\d+)?$/u.test(value)) return Number(value);
91
+ return value;
92
+ }
93
+
94
+ function parseYamlSubset(block) {
95
+ /** @type {Record<string, unknown>} */
96
+ const data = {};
97
+ const lines = block.split(/\r?\n/u);
98
+ for (let i = 0; i < lines.length; i += 1) {
99
+ const line = lines[i] ?? '';
100
+ if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
101
+ if (/^\s/u.test(line)) continue; // continuation of a nested map we do not model
102
+ const match = /^([A-Za-z0-9_.-]+)\s*:(.*)$/u.exec(line);
103
+ if (match === null) continue;
104
+ const key = match[1] ?? '';
105
+ const rest = (match[2] ?? '').trim();
106
+ if (rest === '|' || rest === '>' || rest === '|-' || rest === '>-' || rest === '|+' || rest === '>+') {
107
+ const collected = [];
108
+ while (i + 1 < lines.length && (/^\s+/u.test(lines[i + 1] ?? '') || (lines[i + 1] ?? '').trim() === '')) {
109
+ i += 1;
110
+ collected.push(lines[i] ?? '');
111
+ }
112
+ const indent = Math.min(...collected.filter((l) => l.trim() !== '').map((l) => (/^\s*/u.exec(l)?.[0].length ?? 0)), 1e9);
113
+ const stripped = collected.map((l) => l.slice(Number.isFinite(indent) ? indent : 0));
114
+ data[key] = rest.startsWith('>') ? stripped.join(' ').replace(/\s+/gu, ' ').trim() : stripped.join('\n').replace(/\s+$/u, '');
115
+ continue;
116
+ }
117
+ if (rest === '') {
118
+ // A block list (`- item` lines) or an empty value.
119
+ const items = [];
120
+ while (i + 1 < lines.length && /^\s*-\s+/u.test(lines[i + 1] ?? '')) {
121
+ i += 1;
122
+ items.push(scalar((lines[i] ?? '').replace(/^\s*-\s+/u, '')));
123
+ }
124
+ data[key] = items.length > 0 ? items : '';
125
+ continue;
126
+ }
127
+ data[key] = scalar(rest);
128
+ }
129
+ return data;
130
+ }
131
+
132
+ /**
133
+ * A frontmatter value as a list of non-empty strings: inline/block lists, or one comma-separated string
134
+ * (`applyTo: "**\/*.ts, **\/*.tsx"`).
135
+ * @param {unknown} value
136
+ * @returns {string[]}
137
+ */
138
+ export function asStringList(value) {
139
+ if (Array.isArray(value)) return value.flatMap((item) => asStringList(item));
140
+ if (typeof value !== 'string') return [];
141
+ return splitTopLevelCommas(value).map((item) => item.trim()).filter((item) => item.length > 0);
142
+ }
143
+
144
+ /** Split on commas that are not inside `{…}` (brace alternation keeps its commas). */
145
+ function splitTopLevelCommas(value) {
146
+ const parts = [];
147
+ let depth = 0;
148
+ let current = '';
149
+ for (const ch of value) {
150
+ if (ch === '{') depth += 1;
151
+ if (ch === '}') depth = Math.max(0, depth - 1);
152
+ if (ch === ',' && depth === 0) {
153
+ parts.push(current);
154
+ current = '';
155
+ continue;
156
+ }
157
+ current += ch;
158
+ }
159
+ parts.push(current);
160
+ return parts;
161
+ }
162
+
163
+ /** A frontmatter value as one trimmed string, or undefined. */
164
+ export function asString(value) {
165
+ if (typeof value === 'string') return value.trim().length > 0 ? value.trim() : undefined;
166
+ if (typeof value === 'number' || typeof value === 'boolean') return String(value);
167
+ return undefined;
168
+ }
169
+
170
+ /** A frontmatter value as a boolean, or undefined. */
171
+ export function asBoolean(value) {
172
+ if (typeof value === 'boolean') return value;
173
+ if (typeof value === 'string' && /^(?:true|false)$/iu.test(value.trim())) return value.trim().toLowerCase() === 'true';
174
+ return undefined;
175
+ }
@@ -0,0 +1,114 @@
1
+ // File-pattern matching for scoped rules (Copilot `applyTo`, Cursor/Continue `globs`, Claude `paths`, Kiro
2
+ // `fileMatchPattern`, Windsurf/Devin/Antigravity `globs`). Zero dependencies.
3
+ //
4
+ // Semantics: `**` crosses directories, `*` and `?` stay inside one segment, `{a,b}` alternates, `[abc]` is a class.
5
+ // A pattern with no `/` matches the file name at any depth (`*.ts` == `**/*.ts`), which is what these tools' rule
6
+ // authors expect. A leading `/` or `./` anchors at the project root. Paths are compared as posix, root-relative.
7
+
8
+ const cache = new Map();
9
+
10
+ function expandBraces(pattern) {
11
+ const open = pattern.indexOf('{');
12
+ if (open < 0) return [pattern];
13
+ let depth = 0;
14
+ for (let i = open; i < pattern.length; i += 1) {
15
+ if (pattern[i] === '{') depth += 1;
16
+ else if (pattern[i] === '}') {
17
+ depth -= 1;
18
+ if (depth === 0) {
19
+ const inner = pattern.slice(open + 1, i);
20
+ const options = [];
21
+ let level = 0;
22
+ let start = 0;
23
+ for (let j = 0; j < inner.length; j += 1) {
24
+ if (inner[j] === '{') level += 1;
25
+ else if (inner[j] === '}') level -= 1;
26
+ else if (inner[j] === ',' && level === 0) {
27
+ options.push(inner.slice(start, j));
28
+ start = j + 1;
29
+ }
30
+ }
31
+ options.push(inner.slice(start));
32
+ const head = pattern.slice(0, open);
33
+ const tail = pattern.slice(i + 1);
34
+ return options.flatMap((option) => expandBraces(`${head}${option}${tail}`));
35
+ }
36
+ }
37
+ }
38
+ return [pattern];
39
+ }
40
+
41
+ function segmentToRegex(glob) {
42
+ let out = '';
43
+ for (let i = 0; i < glob.length; i += 1) {
44
+ const ch = glob[i] ?? '';
45
+ if (ch === '*') {
46
+ if (glob[i + 1] === '*') {
47
+ // `**/` = zero or more directories; a trailing `**` = anything.
48
+ if (glob[i + 2] === '/') {
49
+ out += '(?:.*/)?';
50
+ i += 2;
51
+ } else {
52
+ out += '.*';
53
+ i += 1;
54
+ }
55
+ } else out += '[^/]*';
56
+ } else if (ch === '?') out += '[^/]';
57
+ else if (ch === '[') {
58
+ const close = glob.indexOf(']', i + 1);
59
+ if (close < 0) out += '\\[';
60
+ else {
61
+ const body = glob.slice(i + 1, close).replace(/^!/u, '^').replace(/\\/gu, '\\\\');
62
+ out += `[${body}]`;
63
+ i = close;
64
+ }
65
+ } else out += /[.+^${}()|\\]/u.test(ch) ? `\\${ch}` : ch;
66
+ }
67
+ return out;
68
+ }
69
+
70
+ /** Compile one glob (with brace alternation) to an anchored RegExp. */
71
+ export function globToRegExp(pattern) {
72
+ const key = String(pattern);
73
+ const cached = cache.get(key);
74
+ if (cached) return cached;
75
+ let normalized = key.trim().replaceAll('\\', '/');
76
+ let anchored = false;
77
+ if (normalized.startsWith('./')) {
78
+ normalized = normalized.slice(2);
79
+ anchored = true;
80
+ } else if (normalized.startsWith('/')) {
81
+ normalized = normalized.slice(1);
82
+ anchored = true;
83
+ }
84
+ if (normalized.endsWith('/')) normalized += '**';
85
+ const alternatives = expandBraces(normalized).map((alt) => {
86
+ const rooted = anchored || alt.includes('/') ? alt : `**/${alt}`;
87
+ return segmentToRegex(rooted);
88
+ });
89
+ const regex = new RegExp(`^(?:${alternatives.join('|')})$`, 'u');
90
+ cache.set(key, regex);
91
+ return regex;
92
+ }
93
+
94
+ /**
95
+ * Whether a root-relative posix path matches any of the patterns.
96
+ * @param {string} relPath
97
+ * @param {readonly string[]} patterns
98
+ */
99
+ export function matchesAny(relPath, patterns) {
100
+ const path = String(relPath).replaceAll('\\', '/').replace(/^\.\//u, '');
101
+ return patterns.some((pattern) => {
102
+ try {
103
+ return globToRegExp(pattern).test(path);
104
+ } catch {
105
+ return false;
106
+ }
107
+ });
108
+ }
109
+
110
+ /** A pattern that matches every file (`**`, `**\/*`, `*` at any depth): the rule is effectively always-on. */
111
+ export function isMatchAll(pattern) {
112
+ const p = String(pattern).trim();
113
+ return p === '**' || p === '**/*' || p === '*' || p === '/**' || p === '/**/*' || p === './**' || p === './**/*';
114
+ }
@@ -0,0 +1,90 @@
1
+ // Other tools' global instruction files outside the repository (owner spec §4). OPT-IN: every one is OFF until the
2
+ // person turns it on (`globals: { "<id>": true }` in the shared setting), per source. Never make anyone's personal
3
+ // agent policy app-wide: a file here is listed (path, present or not) but never read while its switch is off.
4
+ //
5
+ // Picasso's own global files (`<engine home>/AGENTS.md`, i.e. `$DSH_HOME/AGENTS.md`, and `<Picasso home>/AGENTS.md`) are
6
+ // not in this list: they are Picasso's, and on by default (resolve.js `picassoGlobalCandidates`).
7
+ // Zero dependencies.
8
+
9
+ import { existsSync } from 'node:fs';
10
+ import { join } from 'node:path';
11
+ import { displayGlobalPath, homeDir, picassoGlobalCandidates } from './resolve.js';
12
+
13
+ /**
14
+ * @typedef {object} GlobalSourceSpec
15
+ * @property {string} id the setting key (`globals.<id>`)
16
+ * @property {string} label
17
+ * @property {string} ecosystem
18
+ * @property {readonly string[]} paths home-relative; a trailing `/` marks a folder of rules
19
+ * @property {string} [overrideOf] Codex: `AGENTS.override.md` replaces `AGENTS.md` in the same folder
20
+ */
21
+
22
+ /** @type {readonly GlobalSourceSpec[]} */
23
+ export const GLOBAL_SOURCES = Object.freeze([
24
+ { id: 'codex', label: 'Codex', ecosystem: 'Codex', paths: ['.codex/AGENTS.override.md', '.codex/AGENTS.md'], overrideOf: '.codex/AGENTS.md' },
25
+ { id: 'claude-code', label: 'Claude Code', ecosystem: 'Claude Code', paths: ['.claude/CLAUDE.md'] },
26
+ { id: 'gemini-cli', label: 'Gemini CLI', ecosystem: 'Gemini CLI', paths: ['.gemini/GEMINI.md'] },
27
+ { id: 'qwen', label: 'Qwen Code', ecosystem: 'Qwen Code', paths: ['.qwen/QWEN.md'] },
28
+ { id: 'opencode', label: 'OpenCode', ecosystem: 'OpenCode', paths: ['.config/opencode/AGENTS.md'] },
29
+ { id: 'copilot', label: 'GitHub Copilot', ecosystem: 'GitHub Copilot', paths: ['.copilot/copilot-instructions.md'] },
30
+ { id: 'agents', label: 'Shared agents folder', ecosystem: 'AGENTS.md-compatible tools', paths: ['.agents/AGENTS.md'] },
31
+ { id: 'zed', label: 'Zed', ecosystem: 'Zed', paths: ['.config/zed/AGENTS.md'] },
32
+ { id: 'amp', label: 'Amp', ecosystem: 'Amp', paths: ['.config/amp/AGENTS.md'] },
33
+ { id: 'kilo', label: 'Kilo Code', ecosystem: 'Kilo Code', paths: ['.config/kilo/AGENTS.md'] },
34
+ { id: 'devin', label: 'Devin', ecosystem: 'Devin', paths: ['.devin/global_rules.md'] },
35
+ { id: 'windsurf', label: 'Windsurf', ecosystem: 'Windsurf', paths: ['.codeium/windsurf/memories/global_rules.md'] },
36
+ { id: 'augment', label: 'Augment Code', ecosystem: 'Augment Code', paths: ['.augment/rules/'] },
37
+ { id: 'kiro', label: 'Kiro', ecosystem: 'Kiro', paths: ['.kiro/steering/'] },
38
+ { id: 'roo', label: 'Roo Code', ecosystem: 'Roo Code', paths: ['.roo/rules/'] },
39
+ { id: 'cline', label: 'Cline', ecosystem: 'Cline', paths: ['.cline/rules/'] },
40
+ ]);
41
+
42
+ /** Every id the setting accepts. */
43
+ export const GLOBAL_SOURCE_IDS = Object.freeze(GLOBAL_SOURCES.map((source) => source.id));
44
+
45
+ const absolute = (home, rel) => join(home, ...rel.replace(/\/$/u, '').split('/'));
46
+
47
+ /**
48
+ * Resolver candidates: Picasso's own global file, then every other tool's (in table order). The resolver lists a
49
+ * switched-off candidate without reading it. Codex's override replaces its AGENTS.md when both exist.
50
+ * @param {NodeJS.ProcessEnv} [env]
51
+ * @param {string} [home]
52
+ * @returns {import('./resolve.js').GlobalCandidate[]}
53
+ */
54
+ export function globalCandidates(env = process.env, home = homeDir(env)) {
55
+ const candidates = [...picassoGlobalCandidates(env)];
56
+ for (const spec of GLOBAL_SOURCES) {
57
+ const present = spec.paths.filter((rel) => existsSync(absolute(home, rel)));
58
+ const overridden = spec.overrideOf !== undefined && present.length > 1 ? new Set([spec.overrideOf]) : new Set();
59
+ for (const rel of spec.paths) {
60
+ if (overridden.has(rel)) continue;
61
+ candidates.push({
62
+ id: spec.id,
63
+ label: spec.label,
64
+ ecosystem: spec.ecosystem,
65
+ absolutePath: absolute(home, rel),
66
+ ...(rel.endsWith('/') ? { kind: 'dir' } : {}),
67
+ picassoNative: false,
68
+ });
69
+ }
70
+ }
71
+ return candidates;
72
+ }
73
+
74
+ /**
75
+ * The switches the inspectors show: one row per other-tool source with its paths, whether it is on, and whether
76
+ * anything exists there. Reads only existence, never content.
77
+ * @param {{ globals: Readonly<Record<string, boolean>> }} settings
78
+ * @param {NodeJS.ProcessEnv} [env]
79
+ * @param {string} [home]
80
+ */
81
+ export function globalSourcesReport(settings, env = process.env, home = homeDir(env)) {
82
+ return GLOBAL_SOURCES.map((spec) => ({
83
+ id: spec.id,
84
+ label: spec.label,
85
+ ecosystem: spec.ecosystem,
86
+ paths: spec.paths.map((rel) => displayGlobalPath(absolute(home, rel), home) + (rel.endsWith('/') ? '/' : '')),
87
+ enabled: settings.globals[spec.id] === true,
88
+ present: spec.paths.some((rel) => existsSync(absolute(home, rel))),
89
+ }));
90
+ }
@@ -0,0 +1,123 @@
1
+ // `@path` imports (Claude Code's CLAUDE.md syntax, also used by other tools): `@AGENTS.md`, `@docs/style.md`,
2
+ // `@./rules/x.md`. Imports resolve relative to the importing file, are followed up to MAX_IMPORT_DEPTH, never leave the
3
+ // project root (a home-directory import such as `@~/.claude/x.md` is personal and is reported, not read), and are
4
+ // ignored inside fenced code blocks and inline code. Zero dependencies.
5
+
6
+ import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
7
+ import { readSource } from './scan.js';
8
+
9
+ export const MAX_IMPORT_DEPTH = 5;
10
+
11
+ const IMPORT_TOKEN = /(^|[\s(])@((?:~\/|\.{1,2}\/)?[A-Za-z0-9_.][\w.\-/]*\.(?:md|mdc|txt))(?=$|[\s),.;:!?])/gu;
12
+
13
+ /**
14
+ * Import tokens in a document, outside code. `lineOnly` marks a line that holds nothing but imports.
15
+ * @param {string} text
16
+ * @returns {{ path: string, line: number, lineOnly: boolean }[]}
17
+ */
18
+ export function findImports(text) {
19
+ const found = [];
20
+ let fenced = false;
21
+ const lines = String(text ?? '').split(/\r?\n/u);
22
+ lines.forEach((line, index) => {
23
+ if (/^\s*(?:```|~~~)/u.test(line)) {
24
+ fenced = !fenced;
25
+ return;
26
+ }
27
+ if (fenced) return;
28
+ const withoutCode = line.replace(/`[^`]*`/gu, (span) => ' '.repeat(span.length));
29
+ const tokens = [...withoutCode.matchAll(IMPORT_TOKEN)].map((match) => match[2] ?? '');
30
+ if (tokens.length === 0) return;
31
+ const lineOnly = withoutCode.replace(IMPORT_TOKEN, '$1').trim() === '';
32
+ for (const path of tokens) found.push({ path, line: index, lineOnly });
33
+ });
34
+ return found;
35
+ }
36
+
37
+ function inside(root, path) {
38
+ const rel = relative(root, path);
39
+ return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.startsWith(`..${sep}`));
40
+ }
41
+
42
+ /**
43
+ * @typedef {object} ImportRecord
44
+ * @property {string} request the `@path` as written
45
+ * @property {string} [absolutePath]
46
+ * @property {'expanded' | 'reference' | 'outside-project' | 'missing' | 'cycle' | 'too-deep' | 'error'} status
47
+ */
48
+
49
+ /**
50
+ * Expand a document's imports.
51
+ *
52
+ * `referenceFor(absPath)` returns a short reference (`AGENTS.md`) when the imported file is already rendered as its
53
+ * own source; the import then becomes `(see AGENTS.md above)` instead of a second copy (dedupe including @imports).
54
+ *
55
+ * @param {string} text document body (frontmatter already removed)
56
+ * @param {string} filePath absolute path of the document
57
+ * @param {{ root: string, referenceFor?: (absolutePath: string) => string | undefined, maxSourceBytes?: number }} options
58
+ * @returns {{ text: string, ownText: string, imports: ImportRecord[] }}
59
+ * `ownText`: the document with every import removed (empty when the file is only a pointer)
60
+ */
61
+ export function expandImports(text, filePath, options) {
62
+ /** @type {ImportRecord[]} */
63
+ const records = [];
64
+ const expand = (body, from, depth, chain) => {
65
+ const imports = findImports(body);
66
+ if (imports.length === 0) return { text: body, own: body };
67
+ const lines = body.split(/\r?\n/u);
68
+ const appended = [];
69
+ const ownLines = [...lines];
70
+ const byLine = new Map();
71
+ for (const item of imports) byLine.set(item.line, [...(byLine.get(item.line) ?? []), item]);
72
+ for (const [lineIndex, items] of [...byLine.entries()].sort((a, b) => a[0] - b[0])) {
73
+ const replacements = [];
74
+ for (const item of items) {
75
+ const record = { request: item.path, status: /** @type {ImportRecord['status']} */ ('missing') };
76
+ records.push(record);
77
+ if (item.path.startsWith('~/')) {
78
+ record.status = 'outside-project';
79
+ continue;
80
+ }
81
+ const target = resolve(dirname(from), item.path);
82
+ record.absolutePath = target;
83
+ if (!inside(options.root, target)) {
84
+ record.status = 'outside-project';
85
+ continue;
86
+ }
87
+ if (chain.includes(target)) {
88
+ record.status = 'cycle';
89
+ continue;
90
+ }
91
+ const reference = options.referenceFor?.(target);
92
+ if (reference !== undefined) {
93
+ record.status = 'reference';
94
+ replacements.push(`(see ${reference} above)`);
95
+ continue;
96
+ }
97
+ if (depth >= MAX_IMPORT_DEPTH) {
98
+ record.status = 'too-deep';
99
+ continue;
100
+ }
101
+ const read = readSource(target, options.maxSourceBytes);
102
+ if (!read.ok) {
103
+ record.status = read.error === 'not a file' || read.error.startsWith('cannot read: ENOENT') ? 'missing' : 'error';
104
+ continue;
105
+ }
106
+ record.status = 'expanded';
107
+ const nested = expand(read.text, target, depth + 1, [...chain, target]);
108
+ replacements.push(nested.text.trim());
109
+ }
110
+ if (items.every((item) => item.lineOnly)) {
111
+ lines[lineIndex] = replacements.join('\n\n');
112
+ ownLines[lineIndex] = '';
113
+ } else {
114
+ for (const replacement of replacements) appended.push(replacement);
115
+ // Inline mention: the prose stays (it is the file's own text).
116
+ }
117
+ }
118
+ const expanded = [lines.join('\n').replace(/\n{3,}/gu, '\n\n'), ...appended].filter((part) => part.trim() !== '').join('\n\n');
119
+ return { text: expanded, own: ownLines.join('\n') };
120
+ };
121
+ const result = expand(String(text ?? ''), filePath, 0, [filePath]);
122
+ return { text: result.text, ownText: result.own.trim(), imports: records };
123
+ }