@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,181 @@
1
+ // Find the registry's instruction files in one directory (and its rule folders). Zero dependencies.
2
+ //
3
+ // Never a recursive Markdown sweep: only the fixed paths in formats.js are probed, and only the named rule folders
4
+ // are listed (bounded depth and count). Symlinks are followed for files but a folder is never re-entered.
5
+
6
+ import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
7
+ import { join, posix } from 'node:path';
8
+ import { DOC_FORMATS, FORMATS } from './formats.js';
9
+
10
+ /** Rule folders deeper than this, or with more files than this, are cut off and reported. */
11
+ export const MAX_RULE_DEPTH = 6;
12
+ export const MAX_RULE_FILES = 400;
13
+ /** A single source larger than this is reported as an error and not read (the engine's own source cap). */
14
+ export const DEFAULT_MAX_SOURCE_BYTES = 1_048_576;
15
+
16
+ function statOrUndefined(path) {
17
+ try {
18
+ return statSync(path);
19
+ } catch {
20
+ return undefined;
21
+ }
22
+ }
23
+
24
+ /**
25
+ * List the rule files of one folder, recursively, as posix paths relative to it, sorted.
26
+ * @param {string} dir
27
+ * @param {RegExp} match
28
+ * @returns {{ files: string[], truncated: boolean }}
29
+ */
30
+ export function listRuleFiles(dir, match) {
31
+ const files = [];
32
+ const visited = new Set();
33
+ let truncated = false;
34
+ const walk = (abs, rel, depth) => {
35
+ if (depth > MAX_RULE_DEPTH) {
36
+ truncated = true;
37
+ return;
38
+ }
39
+ let real;
40
+ try {
41
+ real = realpathSync(abs);
42
+ } catch {
43
+ return;
44
+ }
45
+ if (visited.has(real)) return;
46
+ visited.add(real);
47
+ let entries;
48
+ try {
49
+ entries = readdirSync(abs, { withFileTypes: true });
50
+ } catch {
51
+ return;
52
+ }
53
+ entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
54
+ for (const entry of entries) {
55
+ if (files.length >= MAX_RULE_FILES) {
56
+ truncated = true;
57
+ return;
58
+ }
59
+ if (entry.name === 'node_modules' || entry.name === '.git') continue;
60
+ const childAbs = join(abs, entry.name);
61
+ const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
62
+ let isDir = entry.isDirectory();
63
+ let isFile = entry.isFile();
64
+ if (entry.isSymbolicLink()) {
65
+ const target = statOrUndefined(childAbs);
66
+ isDir = target?.isDirectory() ?? false;
67
+ isFile = target?.isFile() ?? false;
68
+ }
69
+ if (isDir) walk(childAbs, childRel, depth + 1);
70
+ else if (isFile && match.test(childRel)) files.push(childRel);
71
+ }
72
+ };
73
+ walk(dir, '', 0);
74
+ return { files: files.sort(), truncated };
75
+ }
76
+
77
+ /**
78
+ * @typedef {object} FoundFile
79
+ * @property {import('./formats.js').InstructionFormat} format
80
+ * @property {string} absolutePath
81
+ * @property {string} relPath posix path relative to the scanned directory (`.cursor/rules/ts.mdc`)
82
+ * @property {string} [mode] Roo mode for `.roo/rules-<mode>/` files
83
+ * @property {boolean} [truncatedFolder] the rule folder hit MAX_RULE_DEPTH / MAX_RULE_FILES
84
+ */
85
+
86
+ /**
87
+ * Every registry file present in `dir`, in registry order (rule folders expanded in sorted order).
88
+ * @param {string} dir absolute directory
89
+ * @param {{ formats?: readonly import('./formats.js').InstructionFormat[], hierarchicalOnly?: boolean }} [options]
90
+ * `hierarchicalOnly`: probe only formats that also apply in nested directories (AGENTS.md, CLAUDE.md, …)
91
+ * @returns {FoundFile[]}
92
+ */
93
+ export function scanDirectory(dir, options = {}) {
94
+ const formats = options.formats ?? FORMATS;
95
+ /** @type {FoundFile[]} */
96
+ const found = [];
97
+ for (const format of formats) {
98
+ if (options.hierarchicalOnly === true && format.hierarchical !== true) continue;
99
+ const abs = join(dir, ...format.path.split('/'));
100
+ const info = statOrUndefined(abs);
101
+ if (info === undefined) continue;
102
+ if (format.shape === 'file') {
103
+ if (info.isFile()) found.push({ format, absolutePath: abs, relPath: format.path });
104
+ continue;
105
+ }
106
+ if (!info.isDirectory() || format.match === undefined) continue;
107
+ const listed = listRuleFiles(abs, format.match);
108
+ const modePattern = format.modeFromDir === undefined ? undefined : new RegExp(format.modeFromDir, 'u');
109
+ for (const rel of listed.files) {
110
+ const mode = modePattern?.exec(rel)?.[1];
111
+ // `.roo` holds both `rules/` (its own row) and `rules-<mode>/`: the mode row takes only mode folders.
112
+ if (modePattern !== undefined && mode === undefined) continue;
113
+ found.push({
114
+ format,
115
+ absolutePath: join(abs, ...rel.split('/')),
116
+ relPath: posix.join(format.path, rel),
117
+ ...(mode === undefined ? {} : { mode }),
118
+ ...(listed.truncated ? { truncatedFolder: true } : {}),
119
+ });
120
+ }
121
+ }
122
+ return found;
123
+ }
124
+
125
+ /**
126
+ * Project docs present in `dir` (§6): indexed by path and size, never read into context.
127
+ * @param {string} dir
128
+ * @returns {{ id: string, label: string, relPath: string, absolutePath: string, bytes: number, note?: string }[]}
129
+ */
130
+ export function scanDocs(dir) {
131
+ const docs = [];
132
+ for (const doc of DOC_FORMATS) {
133
+ const abs = join(dir, ...doc.path.split('/'));
134
+ const info = statOrUndefined(abs);
135
+ if (info === undefined) continue;
136
+ if (doc.shape === 'file' && info.isFile()) {
137
+ docs.push({ id: doc.id, label: doc.label, relPath: doc.path, absolutePath: abs, bytes: info.size, ...(doc.note ? { note: doc.note } : {}) });
138
+ } else if (doc.shape === 'dir' && info.isDirectory() && doc.match) {
139
+ for (const rel of listRuleFiles(abs, doc.match).files) {
140
+ const fileAbs = join(abs, ...rel.split('/'));
141
+ const size = statOrUndefined(fileAbs)?.size ?? 0;
142
+ const relPath = posix.join(doc.path, rel);
143
+ if (docs.some((existing) => existing.relPath === relPath)) continue;
144
+ docs.push({ id: doc.id, label: doc.label, relPath, absolutePath: fileAbs, bytes: size });
145
+ }
146
+ }
147
+ }
148
+ return docs;
149
+ }
150
+
151
+ /**
152
+ * Read one source under a byte cap.
153
+ * @param {string} absolutePath
154
+ * @param {number} [maxSourceBytes]
155
+ * @returns {{ ok: true, text: string, bytes: number, mtimeMs: number } | { ok: false, error: string, bytes?: number }}
156
+ */
157
+ export function readSource(absolutePath, maxSourceBytes = DEFAULT_MAX_SOURCE_BYTES) {
158
+ let info;
159
+ try {
160
+ info = statSync(absolutePath);
161
+ } catch (error) {
162
+ return { ok: false, error: `cannot read: ${error instanceof Error && 'code' in error ? String(error.code) : 'error'}` };
163
+ }
164
+ if (!info.isFile()) return { ok: false, error: 'not a file' };
165
+ if (info.size > maxSourceBytes) return { ok: false, error: `larger than ${maxSourceBytes} bytes`, bytes: info.size };
166
+ try {
167
+ const text = readFileSync(absolutePath, 'utf8');
168
+ return { ok: true, text, bytes: Buffer.byteLength(text, 'utf8'), mtimeMs: info.mtimeMs };
169
+ } catch (error) {
170
+ return { ok: false, error: `cannot read: ${error instanceof Error && 'code' in error ? String(error.code) : 'error'}` };
171
+ }
172
+ }
173
+
174
+ /** Whether a path exists as a directory (lstat: a dangling link is not one). */
175
+ export function isDirectory(path) {
176
+ try {
177
+ return lstatSync(path).isDirectory() || statSync(path).isDirectory();
178
+ } catch {
179
+ return false;
180
+ }
181
+ }
@@ -0,0 +1,150 @@
1
+ // The instruction-discovery setting, shared by the CLI, the TUI and the Mac app:
2
+ // `<settings root>/instructions.json` (`PICASSO_SETTINGS_ROOT`, else `<PICASSO_HOME or ~/.picasso>/settings`), the same
3
+ // directory as settings.json and model-connections.json. Zero dependencies (the engine plugin reads it).
4
+ //
5
+ // { "version": 1, "mode": "smart" | "agents-first" | "native", "nativeAgent": "claude-code" | …,
6
+ // "budgetBytes": 24576, "globals": { "<global source id>": true } }
7
+ //
8
+ // Writers hold `<file>.lock` (the shared-home lock protocol) and replace the file atomically; readers never write.
9
+
10
+ import { readFileSync } from 'node:fs';
11
+ import { userInfo } from 'node:os';
12
+ import { join } from 'node:path';
13
+
14
+ export const SETTINGS_VERSION = 1;
15
+ export const SETTINGS_FILE_NAME = 'instructions.json';
16
+ export const MODES = Object.freeze(['smart', 'agents-first', 'native']);
17
+ export const NATIVE_AGENTS = Object.freeze(['claude-code', 'codex', 'gemini-cli', 'copilot', 'cursor']);
18
+ export const DEFAULT_BUDGET_BYTES = 24_576;
19
+ export const MIN_BUDGET_BYTES = 2_048;
20
+ export const MAX_BUDGET_BYTES = 262_144;
21
+
22
+ /**
23
+ * @typedef {object} InstructionSettings
24
+ * @property {1} version
25
+ * @property {'smart' | 'agents-first' | 'native'} mode
26
+ * @property {'claude-code' | 'codex' | 'gemini-cli' | 'copilot' | 'cursor'} nativeAgent used when mode is `native`
27
+ * @property {number} budgetBytes always-on budget for the Tier-1 instruction block
28
+ * @property {Readonly<Record<string, boolean>>} globals opt-in global sources (default OFF: absent = off)
29
+ */
30
+
31
+ /** @returns {InstructionSettings} */
32
+ export function defaultInstructionSettings() {
33
+ return { version: SETTINGS_VERSION, mode: 'smart', nativeAgent: 'claude-code', budgetBytes: DEFAULT_BUDGET_BYTES, globals: {} };
34
+ }
35
+
36
+ /** The account's Picasso home: PICASSO_HOME, else the OS account's real home (never `$HOME`), like shared-home. */
37
+ export function picassoHomeDir(env = process.env) {
38
+ const configured = env.PICASSO_HOME;
39
+ if (typeof configured === 'string' && configured.trim() !== '') return configured;
40
+ return join(userInfo().homedir, '.picasso');
41
+ }
42
+
43
+ /** `<settings root>/instructions.json`. */
44
+ export function instructionSettingsFile(env = process.env) {
45
+ const root = env.PICASSO_SETTINGS_ROOT;
46
+ const dir = typeof root === 'string' && root.trim() !== '' ? root : join(picassoHomeDir(env), 'settings');
47
+ return join(dir, SETTINGS_FILE_NAME);
48
+ }
49
+
50
+ function clampBudget(value) {
51
+ if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_BUDGET_BYTES;
52
+ return Math.min(MAX_BUDGET_BYTES, Math.max(MIN_BUDGET_BYTES, Math.trunc(value)));
53
+ }
54
+
55
+ /**
56
+ * Any parsed value -> valid settings. Unknown modes fall back to `smart`; only `true` turns a global on.
57
+ * @param {unknown} raw
58
+ * @returns {InstructionSettings}
59
+ */
60
+ export function normalizeInstructionSettings(raw) {
61
+ const base = defaultInstructionSettings();
62
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return base;
63
+ const record = /** @type {Record<string, unknown>} */ (raw);
64
+ const mode = MODES.includes(/** @type {any} */ (record.mode)) ? /** @type {InstructionSettings['mode']} */ (record.mode) : base.mode;
65
+ const nativeAgent = NATIVE_AGENTS.includes(/** @type {any} */ (record.nativeAgent))
66
+ ? /** @type {InstructionSettings['nativeAgent']} */ (record.nativeAgent)
67
+ : base.nativeAgent;
68
+ /** @type {Record<string, boolean>} */
69
+ const globals = {};
70
+ if (record.globals !== null && typeof record.globals === 'object' && !Array.isArray(record.globals)) {
71
+ for (const [id, on] of Object.entries(/** @type {Record<string, unknown>} */ (record.globals)).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
72
+ if (on === true && /^[a-z0-9][a-z0-9-]{0,63}$/u.test(id)) globals[id] = true;
73
+ }
74
+ }
75
+ return { version: SETTINGS_VERSION, mode, nativeAgent, budgetBytes: clampBudget(record.budgetBytes), globals };
76
+ }
77
+
78
+ /**
79
+ * Read the shared setting. A missing file is the defaults; an unreadable or invalid one is the defaults plus `error`
80
+ * (the inspector shows it; nothing is silently "fixed" on disk).
81
+ * @param {NodeJS.ProcessEnv} [env]
82
+ * @returns {{ settings: InstructionSettings, file: string, error?: string }}
83
+ */
84
+ export function readInstructionSettings(env = process.env) {
85
+ const file = instructionSettingsFile(env);
86
+ let text;
87
+ try {
88
+ text = readFileSync(file, 'utf8');
89
+ } catch (error) {
90
+ const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
91
+ if (code === 'ENOENT') return { settings: defaultInstructionSettings(), file };
92
+ return { settings: defaultInstructionSettings(), file, error: `cannot read ${file}` };
93
+ }
94
+ try {
95
+ const parsed = JSON.parse(text);
96
+ if (parsed && typeof parsed === 'object' && typeof parsed.version === 'number' && parsed.version > SETTINGS_VERSION) {
97
+ return { settings: defaultInstructionSettings(), file, error: `${file} was written by a newer Picasso (version ${parsed.version})` };
98
+ }
99
+ return { settings: normalizeInstructionSettings(parsed), file };
100
+ } catch {
101
+ return { settings: defaultInstructionSettings(), file, error: `${file} is not valid JSON` };
102
+ }
103
+ }
104
+
105
+ /**
106
+ * Apply a patch: `mode`, `nativeAgent`, `budgetBytes` replace; `globals` merges per id (`false` removes it).
107
+ * @param {InstructionSettings} current
108
+ * @param {{ mode?: string, nativeAgent?: string, budgetBytes?: number, globals?: Record<string, boolean> }} patch
109
+ * @returns {InstructionSettings}
110
+ */
111
+ export function patchInstructionSettings(current, patch) {
112
+ const globals = { ...current.globals };
113
+ for (const [id, on] of Object.entries(patch.globals ?? {})) {
114
+ if (on === true) globals[id] = true;
115
+ else delete globals[id];
116
+ }
117
+ return normalizeInstructionSettings({
118
+ ...current,
119
+ ...(patch.mode === undefined ? {} : { mode: patch.mode }),
120
+ ...(patch.nativeAgent === undefined ? {} : { nativeAgent: patch.nativeAgent }),
121
+ ...(patch.budgetBytes === undefined ? {} : { budgetBytes: patch.budgetBytes }),
122
+ globals,
123
+ });
124
+ }
125
+
126
+ /** The settings as the file stores them (stable key order). */
127
+ export function serializeInstructionSettings(settings) {
128
+ const normalized = normalizeInstructionSettings(settings);
129
+ return `${JSON.stringify(normalized, null, 2)}\n`;
130
+ }
131
+
132
+ /** `smart`, `agents-first`, or `native:<agent>`: the label the inspector and Tier-1 identity use. */
133
+ export function modeLabel(settings) {
134
+ return settings.mode === 'native' ? `native:${settings.nativeAgent}` : settings.mode;
135
+ }
136
+
137
+ /**
138
+ * Parse a user-typed mode (`smart`, `agents-first`, `agents`, `native:codex`, `claude-code`, …) into a settings patch.
139
+ * @param {string} input
140
+ * @returns {{ mode: InstructionSettings['mode'], nativeAgent?: InstructionSettings['nativeAgent'] } | undefined}
141
+ */
142
+ export function parseModeInput(input) {
143
+ const value = String(input ?? '').trim().toLowerCase();
144
+ if (value === 'smart' || value === 'default') return { mode: 'smart' };
145
+ if (value === 'agents-first' || value === 'agents' || value === 'agents.md' || value === 'agents-md') return { mode: 'agents-first' };
146
+ const agent = value.startsWith('native:') ? value.slice('native:'.length) : value.startsWith('native-') ? value.slice('native-'.length) : value;
147
+ const alias = { claude: 'claude-code', 'claude-code': 'claude-code', codex: 'codex', gemini: 'gemini-cli', 'gemini-cli': 'gemini-cli', copilot: 'copilot', cursor: 'cursor' }[agent];
148
+ if (alias !== undefined) return { mode: 'native', nativeAgent: /** @type {any} */ (alias) };
149
+ return undefined;
150
+ }
@@ -0,0 +1,345 @@
1
+ // The skills, custom-agents and commands registry (owner spec §3): a SEPARATE subsystem from instructions.
2
+ // Metadata first (name, description, path, ecosystem, scope); bodies load on demand; nothing here is injected at
3
+ // session start. A repository with 50 skills costs its listing only, and the listing itself is budgeted.
4
+ //
5
+ // One table of roots for every Picasso consumer: `picasso skills scan` and the TUI `$` picker
6
+ // (apps/cli/src/skills-commands.ts), `/init`'s skill triggers (apps/cli/src/dev-commands.ts and
7
+ // packages/picasso-commands), `skill_search` (packages/picasso-lean-context) and the project commands
8
+ // (packages/commands/src/discovery.ts). The engine plugins ship alone (only their own top-level files), so
9
+ // picasso-commands, picasso-lean-context and packages/commands keep a copy of their slice of these tables; the
10
+ // parity tests in test/skills.test.mjs and packages/commands/test fail when a copy drifts.
11
+ //
12
+ // Zero dependencies. Every function takes explicit `cwd` / `home` / `env`, so tests never read a real home.
13
+
14
+ import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
15
+ import { homedir } from 'node:os';
16
+ import { basename, join, relative, sep } from 'node:path';
17
+ import { asString, parseFrontmatter } from './frontmatter.js';
18
+
19
+ /**
20
+ * Project skill roots (relative to the workspace), in precedence order: the first root wins a duplicate name.
21
+ * `.dsh/skills` and `.agents/skills` are the engine's own project roots; the others are other tools' bundles.
22
+ */
23
+ export const PROJECT_SKILL_ROOTS = Object.freeze([
24
+ Object.freeze({ id: 'picasso', path: '.picasso/skills', ecosystem: 'Picasso' }),
25
+ Object.freeze({ id: 'engine', path: '.dsh/skills', ecosystem: 'Picasso' }),
26
+ Object.freeze({ id: 'agents', path: '.agents/skills', ecosystem: 'Agent Skills' }),
27
+ Object.freeze({ id: 'claude', path: '.claude/skills', ecosystem: 'Claude Code' }),
28
+ Object.freeze({ id: 'github', path: '.github/skills', ecosystem: 'GitHub Copilot' }),
29
+ Object.freeze({ id: 'cursor', path: '.cursor/skills', ecosystem: 'Cursor' }),
30
+ Object.freeze({ id: 'qwen', path: '.qwen/skills', ecosystem: 'Qwen Code' }),
31
+ Object.freeze({ id: 'kiro', path: '.kiro/skills', ecosystem: 'Kiro' }),
32
+ Object.freeze({ id: 'devin', path: '.devin/skills', ecosystem: 'Devin' }),
33
+ ]);
34
+
35
+ /**
36
+ * User skill roots: exactly the ones Picasso already read before this registry (the engine's two homes, Picasso's
37
+ * home, and `~/.claude/skills`, which `skill_search` listed). No other tool's home folder is added here.
38
+ * `env` names the variable that relocates the base folder.
39
+ */
40
+ export const USER_SKILL_ROOTS = Object.freeze([
41
+ Object.freeze({ id: 'engine-home', base: '.dsh', env: 'DSH_HOME', ecosystem: 'Picasso' }),
42
+ Object.freeze({ id: 'agents-home', base: '.agents', env: 'AGENTS_HOME', ecosystem: 'Agent Skills' }),
43
+ Object.freeze({ id: 'picasso-home', base: '.picasso', env: 'PICASSO_HOME', ecosystem: 'Picasso' }),
44
+ Object.freeze({ id: 'claude-home', base: '.claude', ecosystem: 'Claude Code' }),
45
+ ]);
46
+
47
+ /** Custom agents (selected or delegated to; never started by discovery). */
48
+ export const AGENT_ROOTS = Object.freeze([
49
+ Object.freeze({ id: 'claude', path: '.claude/agents', suffix: '.md', ecosystem: 'Claude Code' }),
50
+ Object.freeze({ id: 'github', path: '.github/agents', suffix: '.agent.md', ecosystem: 'GitHub Copilot' }),
51
+ Object.freeze({ id: 'qwen', path: '.qwen/agents', suffix: '.md', ecosystem: 'Qwen Code' }),
52
+ Object.freeze({ id: 'kilo', path: '.kilo/agents', suffix: '.md', ecosystem: 'Kilo Code' }),
53
+ ]);
54
+
55
+ /** Other tools' project commands and prompt files (explicit invocation only), after Picasso's `.picasso/commands`. */
56
+ export const COMMAND_ROOTS = Object.freeze([
57
+ Object.freeze({ id: 'claude', path: '.claude/commands', suffix: '.md', recursive: true, ecosystem: 'Claude Code' }),
58
+ Object.freeze({ id: 'qwen', path: '.qwen/commands', suffix: '.md', recursive: true, ecosystem: 'Qwen Code' }),
59
+ Object.freeze({ id: 'github-prompts', path: '.github/prompts', suffix: '.prompt.md', recursive: false, ecosystem: 'VS Code / GitHub Copilot' }),
60
+ ]);
61
+
62
+ /** Bundles nested deeper than this under a root are not listed; a root lists at most MAX_SKILLS_PER_ROOT bundles. */
63
+ export const MAX_SKILL_DEPTH = 4;
64
+ export const MAX_SKILLS_PER_ROOT = 500;
65
+ /** Metadata reads stop here: the frontmatter, never the body. */
66
+ export const METADATA_READ_BYTES = 16_384;
67
+ /** Default byte budget of a rendered skill index (the lean-context skill-catalog budget). */
68
+ export const DEFAULT_INDEX_BYTES = 2_048;
69
+
70
+ const SKIP_DIRS = new Set(['node_modules', '.git']);
71
+ const toPosix = (path) => path.split(sep).join('/');
72
+
73
+ function homeOf(options) {
74
+ const env = options.env ?? process.env;
75
+ return options.home ?? (typeof env.HOME === 'string' && env.HOME !== '' ? env.HOME : homedir());
76
+ }
77
+
78
+ /**
79
+ * Absolute skill roots for a workspace, in precedence order.
80
+ * @param {{ cwd?: string, home?: string, env?: NodeJS.ProcessEnv, dshHome?: string, includeUser?: boolean }} options
81
+ * `dshHome` overrides the engine home (the CLI passes the session's); `cwd` absent lists only user roots.
82
+ * @returns {{ id: string, dir: string, scope: 'project' | 'user', ecosystem: string }[]}
83
+ */
84
+ export function skillRoots(options = {}) {
85
+ const env = options.env ?? process.env;
86
+ const home = homeOf(options);
87
+ const roots = [];
88
+ if (options.cwd !== undefined) {
89
+ for (const root of PROJECT_SKILL_ROOTS) roots.push({ id: root.id, dir: join(options.cwd, ...root.path.split('/')), scope: 'project', ecosystem: root.ecosystem });
90
+ }
91
+ if (options.includeUser !== false) {
92
+ for (const root of USER_SKILL_ROOTS) {
93
+ const fromEnv = root.env === undefined ? undefined : env[root.env];
94
+ const base = root.id === 'engine-home' && options.dshHome !== undefined
95
+ ? options.dshHome
96
+ : typeof fromEnv === 'string' && fromEnv.trim() !== '' ? fromEnv : join(home, root.base);
97
+ roots.push({ id: root.id, dir: join(base, 'skills'), scope: 'user', ecosystem: root.ecosystem });
98
+ }
99
+ }
100
+ return roots;
101
+ }
102
+
103
+ function isDir(path) {
104
+ try {
105
+ return statSync(path).isDirectory();
106
+ } catch {
107
+ return false;
108
+ }
109
+ }
110
+
111
+ function isFile(path) {
112
+ try {
113
+ return statSync(path).isFile();
114
+ } catch {
115
+ return false;
116
+ }
117
+ }
118
+
119
+ /** The first METADATA_READ_BYTES of a file: enough for frontmatter, never the whole body. */
120
+ export function readHead(path, maxBytes = METADATA_READ_BYTES) {
121
+ let fd;
122
+ try {
123
+ fd = openSync(path, 'r');
124
+ const buffer = Buffer.alloc(maxBytes);
125
+ const read = readSync(fd, buffer, 0, maxBytes, 0);
126
+ return buffer.subarray(0, read).toString('utf8');
127
+ } catch {
128
+ return '';
129
+ } finally {
130
+ if (fd !== undefined) closeSync(fd);
131
+ }
132
+ }
133
+
134
+ /** `name` / `description` (and any other scalar keys) from a file's frontmatter, reading only its head. */
135
+ export function readMetadata(path) {
136
+ const head = readHead(path);
137
+ const { data } = parseFrontmatter(head);
138
+ return { name: asString(data.name), description: asString(data.description), data };
139
+ }
140
+
141
+ /** Skill bundle directories (each holding SKILL.md) under one root, sorted, bounded. */
142
+ export function listSkillBundles(rootDir) {
143
+ const bundles = [];
144
+ const walk = (dir, depth) => {
145
+ if (bundles.length >= MAX_SKILLS_PER_ROOT || depth > MAX_SKILL_DEPTH) return;
146
+ let entries;
147
+ try {
148
+ entries = readdirSync(dir, { withFileTypes: true });
149
+ } catch {
150
+ return;
151
+ }
152
+ entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
153
+ for (const entry of entries) {
154
+ if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
155
+ const child = join(dir, entry.name);
156
+ if (!(entry.isDirectory() || (entry.isSymbolicLink() && isDir(child)))) continue;
157
+ if (isFile(join(child, 'SKILL.md'))) {
158
+ if (bundles.length < MAX_SKILLS_PER_ROOT) bundles.push(child);
159
+ continue; // a bundle's own subfolders (resources, scripts) are not more skills
160
+ }
161
+ walk(child, depth + 1);
162
+ }
163
+ };
164
+ walk(rootDir, 1);
165
+ return bundles;
166
+ }
167
+
168
+ /**
169
+ * @typedef {object} SkillMeta
170
+ * @property {string} name
171
+ * @property {string} [description]
172
+ * @property {string} path the bundle directory
173
+ * @property {string} file its SKILL.md
174
+ * @property {string} root the root directory it was found under
175
+ * @property {string} rootId
176
+ * @property {'project' | 'user'} scope
177
+ * @property {string} ecosystem
178
+ * @property {string} [shadowedBy] a skill of the same name in an earlier root wins
179
+ */
180
+
181
+ /**
182
+ * Every skill under the roots, metadata only, in root precedence order. Same-name skills in later roots are kept and
183
+ * marked `shadowedBy` (callers that need one per name filter on it).
184
+ * @param {{ cwd?: string, home?: string, env?: NodeJS.ProcessEnv, dshHome?: string, includeUser?: boolean }} options
185
+ * @returns {SkillMeta[]}
186
+ */
187
+ export function discoverSkills(options = {}) {
188
+ /** @type {SkillMeta[]} */
189
+ const skills = [];
190
+ const firstByName = new Map();
191
+ for (const root of skillRoots(options)) {
192
+ if (!isDir(root.dir)) continue;
193
+ for (const dir of listSkillBundles(root.dir)) {
194
+ const file = join(dir, 'SKILL.md');
195
+ const meta = readMetadata(file);
196
+ /** @type {SkillMeta} */
197
+ const skill = { name: meta.name ?? basename(dir), path: dir, file, root: root.dir, rootId: root.id, scope: root.scope, ecosystem: root.ecosystem };
198
+ if (meta.description !== undefined) skill.description = meta.description;
199
+ const first = firstByName.get(skill.name);
200
+ if (first !== undefined) skill.shadowedBy = first.path;
201
+ else firstByName.set(skill.name, skill);
202
+ skills.push(skill);
203
+ }
204
+ }
205
+ return skills;
206
+ }
207
+
208
+ /** The body of a skill, agent or command file without its frontmatter: the on-demand read. */
209
+ export function loadBody(file) {
210
+ return parseFrontmatter(readFileSync(file, 'utf8')).body;
211
+ }
212
+
213
+ /** A command name from a file path inside a command folder: `frontend/component.md` -> `frontend-component`. */
214
+ export function commandNameFor(relPath, suffix) {
215
+ const withoutSuffix = relPath.endsWith(suffix) ? relPath.slice(0, -suffix.length) : relPath;
216
+ return withoutSuffix
217
+ .split('/')
218
+ .map((part) => part.replace(/[^A-Za-z0-9_-]+/gu, '-').replace(/^-+|-+$/gu, ''))
219
+ .filter((part) => part.length > 0)
220
+ .join('-');
221
+ }
222
+
223
+ function listFiles(dir, suffix, recursive) {
224
+ const files = [];
225
+ const walk = (current, depth) => {
226
+ let entries;
227
+ try {
228
+ entries = readdirSync(current, { withFileTypes: true });
229
+ } catch {
230
+ return;
231
+ }
232
+ entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
233
+ for (const entry of entries) {
234
+ if (SKIP_DIRS.has(entry.name)) continue;
235
+ const child = join(current, entry.name);
236
+ if (entry.isDirectory()) {
237
+ if (recursive && depth < MAX_SKILL_DEPTH) walk(child, depth + 1);
238
+ } else if ((entry.isFile() || (entry.isSymbolicLink() && isFile(child))) && entry.name.endsWith(suffix)) {
239
+ files.push(child);
240
+ }
241
+ }
242
+ };
243
+ walk(dir, 1);
244
+ return files;
245
+ }
246
+
247
+ /**
248
+ * @typedef {object} DefinitionMeta
249
+ * @property {string} name
250
+ * @property {string} [description]
251
+ * @property {string} path the definition file
252
+ * @property {string} rootId
253
+ * @property {string} ecosystem
254
+ */
255
+
256
+ /**
257
+ * Project custom agents, metadata only. Discovery never starts or registers one as a subagent.
258
+ * @param {{ cwd: string }} options
259
+ * @returns {DefinitionMeta[]}
260
+ */
261
+ export function discoverAgents(options) {
262
+ const agents = [];
263
+ for (const root of AGENT_ROOTS) {
264
+ const dir = join(options.cwd, ...root.path.split('/'));
265
+ for (const file of listFiles(dir, root.suffix, false)) {
266
+ const meta = readMetadata(file);
267
+ const agent = { name: meta.name ?? basename(file).slice(0, -root.suffix.length), path: file, rootId: root.id, ecosystem: root.ecosystem };
268
+ if (meta.description !== undefined) agent.description = meta.description;
269
+ agents.push(agent);
270
+ }
271
+ }
272
+ return agents;
273
+ }
274
+
275
+ /**
276
+ * Other tools' project commands and prompt files, metadata only (explicit invocation; `.picasso/commands` keeps
277
+ * precedence and is read by packages/commands).
278
+ * @param {{ cwd: string }} options
279
+ * @returns {DefinitionMeta[]}
280
+ */
281
+ export function discoverCommands(options) {
282
+ const commands = [];
283
+ for (const root of COMMAND_ROOTS) {
284
+ const dir = join(options.cwd, ...root.path.split('/'));
285
+ for (const file of listFiles(dir, root.suffix, root.recursive)) {
286
+ const name = commandNameFor(toPosix(relative(dir, file)), root.suffix);
287
+ if (name === '') continue;
288
+ const meta = readMetadata(file);
289
+ const command = { name, path: file, rootId: root.id, ecosystem: root.ecosystem };
290
+ if (meta.description !== undefined) command.description = meta.description;
291
+ commands.push(command);
292
+ }
293
+ }
294
+ return commands;
295
+ }
296
+
297
+ /**
298
+ * The whole extension registry for a workspace: skills (project and user), custom agents and commands.
299
+ * @param {{ cwd: string, home?: string, env?: NodeJS.ProcessEnv, dshHome?: string }} options
300
+ */
301
+ export function describeExtensions(options) {
302
+ return { skills: discoverSkills(options), agents: discoverAgents(options), commands: discoverCommands(options) };
303
+ }
304
+
305
+ /**
306
+ * A budgeted skill index: `- name: description` while it fits, then the remaining names only, then "+N more".
307
+ * 50 skills never spend more than `maxBytes`.
308
+ * @param {readonly { name: string, description?: string }[]} skills
309
+ * @param {{ maxBytes?: number, descriptionChars?: number }} [options]
310
+ * @returns {{ text: string, described: number, namesOnly: number, omitted: number }}
311
+ */
312
+ export function renderSkillIndex(skills, options = {}) {
313
+ const maxBytes = options.maxBytes ?? DEFAULT_INDEX_BYTES;
314
+ const descriptionChars = options.descriptionChars ?? 200;
315
+ const bytes = (text) => Buffer.byteLength(text, 'utf8');
316
+ const lines = [];
317
+ let used = 0;
318
+ let index = 0;
319
+ const reserve = 96; // room for the names-only line's tail and the "+N more" marker
320
+ for (; index < skills.length; index += 1) {
321
+ const skill = skills[index];
322
+ if (skill === undefined) break;
323
+ const description = String(skill.description ?? '').replace(/\s+/gu, ' ').trim();
324
+ const short = description.length > descriptionChars ? `${description.slice(0, descriptionChars - 1)}…` : description;
325
+ const line = short === '' ? `- ${skill.name}` : `- ${skill.name}: ${short}`;
326
+ if (used + bytes(line) + 1 > maxBytes - reserve) break;
327
+ lines.push(line);
328
+ used += bytes(line) + 1;
329
+ }
330
+ const described = index;
331
+ const names = [];
332
+ const prefix = 'Also available: ';
333
+ let namesBytes = bytes(prefix);
334
+ for (; index < skills.length; index += 1) {
335
+ const name = skills[index]?.name ?? '';
336
+ const cost = bytes(name) + 2;
337
+ if (used + namesBytes + cost > maxBytes - 40) break;
338
+ names.push(name);
339
+ namesBytes += cost;
340
+ }
341
+ if (names.length > 0) lines.push(`${prefix}${names.join(', ')}`);
342
+ const omitted = skills.length - index;
343
+ if (omitted > 0) lines.push(`+${omitted} more (skill_search)`);
344
+ return { text: lines.join('\n'), described, namesOnly: names.length, omitted };
345
+ }