@minhluudev/ai-tools 0.1.1 → 1.0.1

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.
package/README.md CHANGED
@@ -9,14 +9,35 @@ npm install -g @minhluudev/ai-tools
9
9
  ai-tools install
10
10
  ```
11
11
 
12
+ By default, `ai-tools` and `ai-tools install` run as an interactive terminal UI when executed in a normal terminal. CLI options are only needed for non-interactive or scripted usage.
13
+ Use `← →` to switch tabs, `↑ ↓` to move within a tab, `space` or `enter` to toggle options, and `q` or `esc` to cancel. On the `Review` tab, `enter` confirms the highlighted action.
14
+
15
+ Running `ai-tools` now shows a top-level menu with:
16
+
17
+ 1. `Install agent skills`
18
+ 2. `Install project docs`
19
+ 3. `Install libs for AI`
20
+ 4. `Cancel`
21
+
22
+ `Install project docs` now opens its own terminal UI with two tabs: `Skills` and `Review`.
23
+ `Install libs for AI` is still a placeholder until that flow is implemented.
24
+
12
25
  ## Supported Flow
13
26
 
14
27
  The interactive installer asks for:
15
28
 
16
- 1. Individual skills from the `skill-general` branch
17
- 2. Skill groups from other branches such as `laravel-ddd`
18
- 3. Installation location: `global` or `local`
19
- 4. Target agent: `codex` or `claude`
29
+ 1. Individual skills from the local selection catalog packaged with the CLI
30
+ 2. Installation locations: `global`, `local`, or both
31
+ 3. Target agents: `codex`, `claude`, or both
32
+ 4. A review tab where you can confirm or cancel after navigating back and forth with the tab bar
33
+
34
+ The project docs installer asks for:
35
+
36
+ 1. Skills from the local `project-docs-catalog.json`
37
+ 2. A `Review` tab where you can confirm, go back to the main menu, or cancel
38
+ 3. Copy the contents inside the selected folder directly into the current working directory
39
+
40
+ The wizard does not validate GitHub branches or manifests while you are selecting options. Source validation only starts after you confirm the review step.
20
41
 
21
42
  Global installs write into:
22
43
 
@@ -32,6 +53,8 @@ Local installs write into:
32
53
 
33
54
  Each source branch must expose `ai-tools.catalog.json` at the branch root.
34
55
 
56
+ The menu shown by the wizard is driven by `selection-catalog.json` in this package. Update that file when you add or rename installable skills.
57
+
35
58
  ```json
36
59
  {
37
60
  "version": 1,
@@ -40,18 +63,18 @@ Each source branch must expose `ai-tools.catalog.json` at the branch root.
40
63
  "description": "Standalone skills",
41
64
  "items": [
42
65
  {
43
- "id": "laravel-code-reviewer",
44
- "label": "Laravel Code Reviewer",
45
- "description": "Review Laravel and PHP changes",
46
- "sourcePath": "skills/laravel-code-reviewer",
66
+ "id": "git-engineering-workflow",
67
+ "label": "Git engineering workflow",
68
+ "description": "Folder: git-engineering-workflow",
69
+ "sourcePath": "skills/git-engineering-workflow",
47
70
  "targets": {
48
71
  "codex": {
49
72
  "type": "directory",
50
- "outputPath": "skills/laravel-code-reviewer"
73
+ "outputPath": "skills/git-engineering-workflow"
51
74
  },
52
75
  "claude": {
53
76
  "type": "file",
54
- "outputPath": "agents/laravel-code-reviewer.md"
77
+ "outputPath": "agents/git-engineering-workflow.md"
55
78
  }
56
79
  }
57
80
  }
@@ -61,7 +84,7 @@ Each source branch must expose `ai-tools.catalog.json` at the branch root.
61
84
 
62
85
  Rules:
63
86
 
64
- - `skill-general` must use `"type": "skills"`
87
+ - `agent-skills` must use `"type": "skills"`
65
88
  - group branches must use `"type": "group"`
66
89
  - `sourcePath` and `outputPath` must stay inside the repository or install root
67
90
  - each selected skill id must be unique across the final merged selection
@@ -70,10 +93,9 @@ Rules:
70
93
 
71
94
  ```bash
72
95
  ai-tools install \
73
- --skills laravel-code-reviewer,mql5-ui-designer \
74
- --groups laravel-ddd \
75
- --location local \
76
- --agent codex \
96
+ --skills git-engineering-workflow,review-code \
97
+ --location local,global \
98
+ --agent codex,claude \
77
99
  --yes
78
100
  ```
79
101
 
@@ -1,7 +1,15 @@
1
1
  #!/usr/bin/env node
2
2
  import { runCli } from "../cli.js";
3
+ function isCancellationMessage(message) {
4
+ return message === "Installation cancelled."
5
+ || message === "Installation cancelled because existing targets would be overwritten.";
6
+ }
3
7
  runCli(process.argv).catch((error) => {
4
8
  const message = error instanceof Error ? error.message : String(error);
9
+ if (isCancellationMessage(message)) {
10
+ process.exitCode = 0;
11
+ return;
12
+ }
5
13
  console.error(`Error: ${message}`);
6
14
  process.exitCode = 1;
7
15
  });
package/dist/src/cli.js CHANGED
@@ -1,214 +1,228 @@
1
1
  import * as process from "node:process";
2
2
  import { parseArgs, printHelp } from "./lib/args.js";
3
3
  import { loadPackageConfig } from "./lib/config.js";
4
- import { loadCatalogIndex, mergeSelectedItems } from "./lib/catalog.js";
5
- import { createPromptSession, promptConfirm, promptMultiSelect, promptSingleSelect } from "./lib/prompts.js";
4
+ import { createPromptSession, promptConfirm } from "./lib/prompts.js";
6
5
  import { createGitHubClient } from "./lib/github.js";
7
- import { detectExistingTargets, installPlannedItems, planInstallations, resolveInstallRoot } from "./lib/install.js";
8
- function formatSelectionChoices(items) {
9
- return items.map((item) => {
10
- const compatibility = [item.targets.codex ? "codex" : null, item.targets.claude ? "claude" : null]
11
- .filter(Boolean)
12
- .join(", ");
13
- return {
14
- value: item.id,
15
- label: item.label,
16
- description: `${item.description || "No description"} [${compatibility || "unsupported"}]`
17
- };
18
- });
19
- }
20
- function formatGroupChoices(groups) {
21
- return groups.map((group) => ({
22
- value: group.id,
23
- label: group.label,
24
- description: `${group.description || "No description"} (${group.items.length} skill${group.items.length === 1 ? "" : "s"})`
25
- }));
26
- }
27
- function printSelectionSummary(input) {
6
+ import { detectExistingTargets, installPlannedItems, installProjectDocsItems, planInstallations, planProjectDocsInstallations, resolveInstallRoot, resolveProjectDocsRoot } from "./lib/install.js";
7
+ import { loadProjectDocsCatalog } from "./lib/project-docs-catalog.js";
8
+ import { loadSelectionCatalog, resolveSelectionItems } from "./lib/selection-catalog.js";
9
+ import { runEntryMenu } from "./lib/tui-entry-menu.js";
10
+ import { runProjectDocsWizard } from "./lib/tui-project-docs.js";
11
+ import { runTabbedWizard } from "./lib/tui-wizard.js";
12
+ function printSectionHeader(title, subtitle) {
13
+ const lines = [
14
+ `AI-TOOLS :: ${title}`,
15
+ subtitle
16
+ ];
17
+ const width = Math.max(...lines.map((line) => line.length)) + 4;
18
+ const border = "+".padEnd(width - 1, "-") + "+";
28
19
  console.log("");
29
- console.log("Install summary");
30
- console.log(`- Agent: ${input.agent}`);
31
- console.log(`- Location: ${input.location}`);
32
- console.log(`- Root: ${input.installRoot}`);
33
- console.log(`- Individual skills: ${input.selectedSkills.length ? input.selectedSkills.join(", ") : "none"}`);
34
- console.log(`- Groups: ${input.selectedGroups.length ? input.selectedGroups.join(", ") : "none"}`);
35
- console.log(`- Final items: ${input.plannedItems.map((item) => item.id).join(", ")}`);
36
- }
37
- async function resolveInteractiveSelections(index, options) {
38
- const prompt = createPromptSession();
39
- try {
40
- const selectedSkills = options.skills.length > 0
41
- ? options.skills
42
- : await promptMultiSelect(prompt, {
43
- message: "Select individual skills",
44
- choices: formatSelectionChoices(index.individualSkills),
45
- allowEmpty: true
46
- });
47
- const selectedGroups = options.groups.length > 0
48
- ? options.groups
49
- : await promptMultiSelect(prompt, {
50
- message: "Select skill groups",
51
- choices: formatGroupChoices(index.groups),
52
- allowEmpty: true
53
- });
54
- const location = options.location ||
55
- (await promptSingleSelect(prompt, {
56
- message: "Select installation location",
57
- choices: [
58
- {
59
- value: "global",
60
- label: "global",
61
- description: "Install into the current user's home directory."
62
- },
63
- {
64
- value: "local",
65
- label: "local",
66
- description: "Install into this project's dot directories."
67
- }
68
- ]
69
- }));
70
- const agent = options.agent ||
71
- (await promptSingleSelect(prompt, {
72
- message: "Select agent",
73
- choices: [
74
- {
75
- value: "codex",
76
- label: "codex",
77
- description: "Install as Codex skills."
78
- },
79
- {
80
- value: "claude",
81
- label: "claude",
82
- description: "Install as Claude custom agents."
83
- }
84
- ]
85
- }));
86
- return { selectedSkills, selectedGroups, location, agent };
87
- }
88
- finally {
89
- await prompt.close();
20
+ console.log(border);
21
+ for (const line of lines) {
22
+ console.log(`| ${line.padEnd(width - 4, " ")} |`);
90
23
  }
24
+ console.log(border);
25
+ console.log("");
26
+ }
27
+ function printSkillSelectionSummary(input) {
28
+ const selectedSkillLabels = input.selectionCatalog.skills
29
+ .filter((skill) => input.selectedSkills.includes(skill.id))
30
+ .map((skill) => skill.label);
31
+ const selectedGroupLabels = input.selectionCatalog.groups
32
+ .filter((group) => input.selectedGroups.includes(group.id))
33
+ .map((group) => group.label);
34
+ console.log("Selected items:");
35
+ console.log(`- Skills: ${selectedSkillLabels.length ? selectedSkillLabels.join(", ") : "none"}`);
36
+ if (selectedGroupLabels.length > 0) {
37
+ console.log(`- Groups: ${selectedGroupLabels.join(", ")}`);
38
+ }
39
+ console.log(`- Locations: ${input.locations.length ? input.locations.join(", ") : "none"}`);
40
+ console.log(`- Agents: ${input.agents.length ? input.agents.join(", ") : "none"}`);
91
41
  }
92
- function ensureNonInteractiveInputs(index, options) {
42
+ function printProjectDocsSelectionSummary(input) {
43
+ console.log("Selected items:");
44
+ console.log(`- Skills: ${input.selectedSkills.map((skill) => skill.label).join(", ")}`);
45
+ console.log(`- Install root: ${resolveProjectDocsRoot(input.cwd)}`);
46
+ }
47
+ function ensureNonInteractiveInputs(selectionCatalog, options) {
93
48
  const missing = [];
94
49
  if (options.skills.length === 0 && options.groups.length === 0) {
95
50
  missing.push("--skills and/or --groups");
96
51
  }
97
- if (!options.location) {
52
+ if (options.locations.length === 0) {
98
53
  missing.push("--location");
99
54
  }
100
- if (!options.agent) {
55
+ if (options.agents.length === 0) {
101
56
  missing.push("--agent");
102
57
  }
103
58
  if (missing.length > 0) {
104
59
  throw new Error(`Non-interactive mode requires ${missing.join(", ")}. Run in a TTY for prompts.`);
105
60
  }
106
- const unknownSkills = options.skills.filter((skillId) => !index.individualSkills.some((item) => item.id === skillId));
61
+ const unknownSkills = options.skills.filter((skillId) => !selectionCatalog.skills.some((item) => item.id === skillId));
107
62
  if (unknownSkills.length > 0) {
108
63
  throw new Error(`Unknown skill id(s): ${unknownSkills.join(", ")}`);
109
64
  }
110
- const unknownGroups = options.groups.filter((groupId) => !index.groups.some((group) => group.id === groupId));
65
+ const unknownGroups = options.groups.filter((groupId) => !selectionCatalog.groups.some((group) => group.id === groupId));
111
66
  if (unknownGroups.length > 0) {
112
67
  throw new Error(`Unknown group id(s): ${unknownGroups.join(", ")}`);
113
68
  }
114
69
  }
115
- async function resolveSelections(index, options) {
70
+ async function resolveSelections(selectionCatalog, options) {
116
71
  if (!process.stdin.isTTY || !process.stdout.isTTY) {
117
- ensureNonInteractiveInputs(index, options);
72
+ ensureNonInteractiveInputs(selectionCatalog, options);
118
73
  return {
119
74
  selectedSkills: options.skills,
120
75
  selectedGroups: options.groups,
121
- location: options.location,
122
- agent: options.agent
76
+ locations: options.locations,
77
+ agents: options.agents
123
78
  };
124
79
  }
125
- return resolveInteractiveSelections(index, options);
80
+ return runTabbedWizard(selectionCatalog, options, "Install agent skills");
126
81
  }
127
- export async function runCli(argv = process.argv) {
128
- const { command, options } = parseArgs(argv.slice(2));
129
- if (options.help || command === "help") {
130
- printHelp();
131
- return;
132
- }
133
- if (command !== "install") {
134
- throw new Error(`Unsupported command "${command}". Only "install" is available.`);
135
- }
136
- const config = await loadPackageConfig();
137
- const client = createGitHubClient(config.github);
138
- console.log("Loading remote catalogs...");
139
- const index = await loadCatalogIndex(client, config.github);
140
- if (index.individualSkills.length === 0 && index.groups.length === 0) {
141
- throw new Error("No installable skills or groups were found in the configured repository.");
142
- }
143
- const { selectedSkills, selectedGroups, location, agent } = await resolveSelections(index, options);
144
- const finalItems = mergeSelectedItems({
145
- individualSkills: index.individualSkills,
146
- groups: index.groups,
147
- selectedSkillIds: selectedSkills,
148
- selectedGroupIds: selectedGroups
149
- });
150
- if (finalItems.length === 0) {
151
- throw new Error("No skills were selected.");
82
+ async function resolveEntryAction(rawArgs) {
83
+ if (rawArgs.length > 0 || !process.stdin.isTTY || !process.stdout.isTTY) {
84
+ return null;
152
85
  }
153
- const installRoot = resolveInstallRoot({ agent, location, cwd: process.cwd() });
154
- const plannedItems = planInstallations({
155
- items: finalItems,
156
- agent,
157
- installRoot
158
- });
159
- printSelectionSummary({
160
- location,
161
- agent,
162
- installRoot,
163
- selectedSkills,
164
- selectedGroups,
165
- plannedItems
166
- });
167
- const existingTargets = await detectExistingTargets(plannedItems);
168
- let overwriteExisting = options.yes;
169
- if (existingTargets.length > 0 && !overwriteExisting) {
170
- console.log("");
171
- console.log("Existing targets detected:");
172
- for (const item of existingTargets) {
173
- console.log(`- ${item.id}: ${item.targetPath}`);
174
- }
175
- if (!process.stdin.isTTY || !process.stdout.isTTY) {
176
- throw new Error("Existing targets require --yes in non-interactive mode.");
86
+ return runEntryMenu();
87
+ }
88
+ export async function runCli(argv = process.argv) {
89
+ const rawArgs = argv.slice(2);
90
+ const useMainMenu = rawArgs.length === 0 && process.stdin.isTTY && process.stdout.isTTY;
91
+ while (true) {
92
+ const entryAction = useMainMenu ? await resolveEntryAction(rawArgs) : null;
93
+ if (entryAction === "install-libs") {
94
+ printSectionHeader("Install libs for AI", "Shared AI libraries and tooling are not implemented yet.");
95
+ console.log("Install libs for AI is not implemented yet.");
96
+ return;
177
97
  }
178
- const prompt = createPromptSession();
179
- try {
180
- overwriteExisting = await promptConfirm(prompt, {
181
- message: "Overwrite all existing targets?",
182
- defaultValue: false
98
+ if (entryAction === "install-project-docs") {
99
+ const config = await loadPackageConfig();
100
+ const projectDocsCatalog = await loadProjectDocsCatalog(config);
101
+ const projectDocsResult = await runProjectDocsWizard(projectDocsCatalog);
102
+ if ("backToMenu" in projectDocsResult) {
103
+ if (useMainMenu) {
104
+ continue;
105
+ }
106
+ return;
107
+ }
108
+ printSectionHeader("Install project docs", "Preparing selected project docs for resolution and installation.");
109
+ printProjectDocsSelectionSummary({
110
+ selectedSkills: projectDocsResult.selectedSkills,
111
+ cwd: process.cwd()
183
112
  });
113
+ console.log("Resolving selected sources...");
114
+ const client = createGitHubClient(config.github);
115
+ const plannedItems = planProjectDocsInstallations({
116
+ skills: projectDocsResult.selectedSkills,
117
+ cwd: process.cwd()
118
+ });
119
+ console.log("");
120
+ console.log("Installing...");
121
+ const results = await installProjectDocsItems({
122
+ plannedItems,
123
+ client,
124
+ overwriteExisting: false,
125
+ onProgress(item) {
126
+ console.log(`- ${item.id} from ${item.sourceBranch} -> ${item.targetPath}`);
127
+ }
128
+ });
129
+ console.log("");
130
+ console.log("Install complete");
131
+ for (const result of results) {
132
+ console.log(`- ${result.id}: ${result.targetPath}`);
133
+ }
134
+ return;
184
135
  }
185
- finally {
186
- await prompt.close();
136
+ if (entryAction === "cancel") {
137
+ return;
187
138
  }
188
- if (!overwriteExisting) {
189
- throw new Error("Installation cancelled because existing targets would be overwritten.");
139
+ const effectiveArgs = entryAction === "install-skills" ? ["install"] : rawArgs;
140
+ const { command, options } = parseArgs(effectiveArgs);
141
+ if (options.help || command === "help") {
142
+ printHelp();
143
+ return;
190
144
  }
191
- }
192
- console.log("");
193
- console.log("Installing...");
194
- const results = await installPlannedItems({
195
- plannedItems,
196
- client,
197
- overwriteExisting,
198
- onProgress(item) {
199
- console.log(`- ${item.id} from ${item.sourceBranch} -> ${item.targetPath}`);
145
+ if (command !== "install") {
146
+ throw new Error(`Unsupported command "${command}". Only "install" is available.`);
147
+ }
148
+ const config = await loadPackageConfig();
149
+ const selectionCatalog = await loadSelectionCatalog(config);
150
+ if (selectionCatalog.skills.length === 0 && selectionCatalog.groups.length === 0) {
151
+ throw new Error("Selection catalog is empty. Add skills or groups before running the installer.");
152
+ }
153
+ const selectionResult = await resolveSelections(selectionCatalog, options);
154
+ if ("backToMenu" in selectionResult) {
155
+ if (useMainMenu) {
156
+ continue;
157
+ }
158
+ return;
159
+ }
160
+ const { selectedSkills, selectedGroups, locations, agents } = selectionResult;
161
+ printSectionHeader("Install agent skills", "Preparing selected skills for resolution and installation.");
162
+ printSkillSelectionSummary({
163
+ selectionCatalog,
164
+ selectedSkills,
165
+ selectedGroups,
166
+ locations,
167
+ agents
168
+ });
169
+ console.log("Resolving selected sources...");
170
+ const client = createGitHubClient(config.github);
171
+ const finalItems = await resolveSelectionItems({
172
+ client,
173
+ config,
174
+ selectionCatalog,
175
+ selectedSkillIds: selectedSkills,
176
+ selectedGroupIds: selectedGroups
177
+ });
178
+ if (finalItems.length === 0) {
179
+ throw new Error("No installable items were resolved from the selected sources.");
180
+ }
181
+ const plannedItems = locations.flatMap((location) => agents.flatMap((agent) => planInstallations({
182
+ items: finalItems,
183
+ agent,
184
+ installRoot: resolveInstallRoot({ agent, location, cwd: process.cwd() })
185
+ })));
186
+ const existingTargets = await detectExistingTargets(plannedItems);
187
+ let overwriteExisting = options.yes;
188
+ if (existingTargets.length > 0 && !overwriteExisting) {
189
+ console.log("");
190
+ console.log("Existing targets detected:");
191
+ for (const item of existingTargets) {
192
+ console.log(`- ${item.id}: ${item.targetPath}`);
193
+ }
194
+ if (!process.stdin.isTTY || !process.stdout.isTTY) {
195
+ throw new Error("Existing targets require --yes in non-interactive mode.");
196
+ }
197
+ const prompt = createPromptSession();
198
+ try {
199
+ overwriteExisting = await promptConfirm(prompt, {
200
+ message: "Overwrite all existing targets?",
201
+ defaultValue: false
202
+ });
203
+ }
204
+ finally {
205
+ await prompt.close();
206
+ }
207
+ if (!overwriteExisting) {
208
+ throw new Error("Installation cancelled because existing targets would be overwritten.");
209
+ }
200
210
  }
201
- });
202
- console.log("");
203
- console.log("Install complete");
204
- for (const result of results) {
205
- console.log(`- ${result.id}: ${result.targetPath}`);
206
- }
207
- if (index.warnings.length > 0) {
208
211
  console.log("");
209
- console.log("Catalog warnings");
210
- for (const warning of index.warnings) {
211
- console.log(`- ${warning}`);
212
+ console.log("Installing...");
213
+ const results = await installPlannedItems({
214
+ plannedItems,
215
+ client,
216
+ overwriteExisting,
217
+ onProgress(item) {
218
+ console.log(`- ${item.id} from ${item.sourceBranch} -> ${item.targetPath}`);
219
+ }
220
+ });
221
+ console.log("");
222
+ console.log("Install complete");
223
+ for (const result of results) {
224
+ console.log(`- ${result.id}: ${result.targetPath}`);
212
225
  }
226
+ return;
213
227
  }
214
228
  }
@@ -22,8 +22,8 @@ export function parseArgs(argv) {
22
22
  const options = {
23
23
  help: false,
24
24
  yes: false,
25
- agent: undefined,
26
- location: undefined,
25
+ agents: [],
26
+ locations: [],
27
27
  skills: [],
28
28
  groups: []
29
29
  };
@@ -58,17 +58,19 @@ export function parseArgs(argv) {
58
58
  continue;
59
59
  }
60
60
  if (key === "agent") {
61
- if (!isAgent(value)) {
62
- throw new Error(`Invalid agent "${value}". Use "codex" or "claude".`);
61
+ const agents = parseCsv(value);
62
+ if (agents.some((agent) => !isAgent(agent))) {
63
+ throw new Error(`Invalid agent list "${value}". Use "codex" and/or "claude".`);
63
64
  }
64
- options.agent = value;
65
+ options.agents = agents;
65
66
  continue;
66
67
  }
67
68
  if (key === "location") {
68
- if (!isInstallLocation(value)) {
69
- throw new Error(`Invalid location "${value}". Use "global" or "local".`);
69
+ const locations = parseCsv(value);
70
+ if (locations.some((location) => !isInstallLocation(location))) {
71
+ throw new Error(`Invalid location list "${value}". Use "global" and/or "local".`);
70
72
  }
71
- options.location = value;
73
+ options.locations = locations;
72
74
  }
73
75
  }
74
76
  return { command, options };
@@ -77,14 +79,19 @@ export function printHelp() {
77
79
  console.log(`ai-tools
78
80
 
79
81
  Usage:
82
+ ai-tools
80
83
  ai-tools install [options]
81
84
  ai-tools help
82
85
 
86
+ Default behavior:
87
+ Running "ai-tools" in an interactive terminal opens a top-level menu.
88
+ Running "ai-tools install" starts the skills installer directly.
89
+
83
90
  Options:
84
91
  --skills <ids> Comma-separated individual skill ids
85
92
  --groups <ids> Comma-separated group ids
86
- --location <type> global | local
87
- --agent <agent> codex | claude
93
+ --location <types> Comma-separated: global,local
94
+ --agent <agents> Comma-separated: codex,claude
88
95
  --yes Skip overwrite prompts
89
96
  --help, -h Show help
90
97
  `);
@@ -86,25 +86,57 @@ export function validateManifest(rawManifest, input) {
86
86
  function isSkillGroup(group) {
87
87
  return group !== null;
88
88
  }
89
+ async function tryLoadManifest(client, input) {
90
+ try {
91
+ const rawManifest = await client.fetchManifest(input);
92
+ return validateManifest(rawManifest, {
93
+ branch: input.branch,
94
+ manifestPath: input.manifestPath
95
+ });
96
+ }
97
+ catch {
98
+ return null;
99
+ }
100
+ }
89
101
  export async function loadCatalogIndex(client, githubConfig) {
90
102
  const warnings = [];
91
103
  const branches = await client.listBranches();
92
104
  const branchMap = new Map(branches.map((branch) => [branch.name, branch]));
93
- const skillsBranch = branchMap.get(githubConfig.skillsBranch);
94
- if (!skillsBranch) {
95
- throw new Error(`Configured skills branch "${githubConfig.skillsBranch}" was not found.`);
105
+ const configuredSkillsBranch = branchMap.get(githubConfig.skillsBranch);
106
+ const defaultBranch = branchMap.get(githubConfig.defaultBranch);
107
+ let skillsBranch = configuredSkillsBranch;
108
+ let skillManifest = null;
109
+ if (configuredSkillsBranch) {
110
+ skillManifest = await tryLoadManifest(client, {
111
+ branch: configuredSkillsBranch.name,
112
+ sha: configuredSkillsBranch.sha,
113
+ manifestPath: githubConfig.manifestPath
114
+ });
115
+ }
116
+ if (!skillManifest && defaultBranch) {
117
+ const defaultManifest = await tryLoadManifest(client, {
118
+ branch: defaultBranch.name,
119
+ sha: defaultBranch.sha,
120
+ manifestPath: githubConfig.manifestPath
121
+ });
122
+ if (defaultManifest) {
123
+ skillsBranch = defaultBranch;
124
+ skillManifest = defaultManifest;
125
+ if (!configuredSkillsBranch) {
126
+ warnings.push(`Configured skills branch "${githubConfig.skillsBranch}" was not found. Falling back to "${defaultBranch.name}".`);
127
+ }
128
+ else if (configuredSkillsBranch.name !== defaultBranch.name) {
129
+ warnings.push(`Configured skills branch "${githubConfig.skillsBranch}" does not contain a valid manifest. Falling back to "${defaultBranch.name}".`);
130
+ }
131
+ }
132
+ }
133
+ if (!skillsBranch || !skillManifest) {
134
+ const availableBranches = branches.map((branch) => branch.name).join(", ") || "none";
135
+ throw new Error(`Could not load skills catalog. Expected "${githubConfig.manifestPath}" in branch "${githubConfig.skillsBranch}"` +
136
+ ` or fallback branch "${githubConfig.defaultBranch}". Available branches: ${availableBranches}.`);
96
137
  }
97
- const skillManifestRaw = await client.fetchManifest({
98
- branch: skillsBranch.name,
99
- sha: skillsBranch.sha,
100
- manifestPath: githubConfig.manifestPath
101
- });
102
- const skillManifest = validateManifest(skillManifestRaw, {
103
- branch: skillsBranch.name,
104
- manifestPath: githubConfig.manifestPath
105
- });
106
138
  const excludedBranches = new Set([
107
- githubConfig.skillsBranch,
139
+ skillsBranch.name,
108
140
  ...githubConfig.excludeBranches,
109
141
  githubConfig.defaultBranch
110
142
  ]);
@@ -12,6 +12,8 @@ export async function loadPackageConfig() {
12
12
  }
13
13
  return {
14
14
  packageRoot: PACKAGE_ROOT,
15
+ selectionCatalogPath: aiTools.selectionCatalogPath || "selection-catalog.json",
16
+ projectDocsCatalogPath: aiTools.projectDocsCatalogPath || "project-docs-catalog.json",
15
17
  github: {
16
18
  owner: aiTools.github.owner,
17
19
  repo: aiTools.github.repo,