td-ai-tools 1.1.11 → 1.2.0

package/README.md

@@ -36,9 +36,11 @@ npx td-ai-tools list
 npx td-ai-tools install
 npx td-ai-tools install --all
 npx td-ai-tools install pr-solver
+npx td-ai-tools install --setup playwright-cli
 npx td-ai-tools install pr-solver horizon-component-library
 npx td-ai-tools update
 npx td-ai-tools update --all
+npx td-ai-tools update --setup playwright-cli
 npx td-ai-tools update pr-solver
 npx td-ai-tools delete
 npx td-ai-tools delete --all
@@ -53,6 +55,8 @@ If a skill bundles a sub-agent prompt (any `.md` with a `name:` field in `skills
 
 This keeps the installed assets available to both Claude-style and `.agents`-style project conventions.
 
+Some skills provide a recognized setup command (`setup.sh`, `scripts/setup.sh`, or `package.json` with `scripts.setup`). Non-interactive installs and updates run setup only when you pass `--setup`; interactive installs/updates ask for confirmation only when the selected skills include a recognized setup command. Accepted setup runs once inside each installed copy: `.claude/skills/<name>/` and `.agents/skills/<name>/`.
+
 `install` now errors when the target item already exists. Use `update` to replace an existing installed skill or agent pack.
 
 `delete` removes installed items from both `.claude/` and `.agents/` target directories, and works on any installed skill or agent pack regardless of whether it is in the catalogue.

package/bin/cli.js

@@ -12,7 +12,7 @@ import {
 } from '../lib/catalog.js';
 import { readFrontmatterField } from '../lib/frontmatter.js';
 import {
-  installSkill, installAgent, deleteSkill, deleteAgent,
+  installSkill, installAgent, deleteSkill, deleteAgent, skillHasSetup,
 } from '../lib/installer.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -139,13 +139,18 @@ function hintFor(type, name) {
  *
  * @param {MenuItem[]} items - Items to install.
  * @param {{replaceExisting?: boolean}} [options] - Forwarded to the installer.
- * @returns {void}
+ * @returns {boolean} Whether every installer reported success.
  */
 function installItems(items, options = {}) {
+  const { runSetup = false, ...installOptions } = options;
+  let ok = true;
   for (const item of items) {
-    if (item.type === 'skill') installSkill(ctx, item.name, { ...options, report: status });
-    else installAgent(ctx, item.name, { ...options, report: status });
+    const installed = item.type === 'skill'
+      ? installSkill(ctx, item.name, { ...installOptions, runSetup, report: status })
+      : installAgent(ctx, item.name, { ...installOptions, report: status });
+    if (!installed) ok = false;
   }
+  return ok;
 }
 
 /**
@@ -354,6 +359,52 @@ function fromGroupValues(values) {
   });
 }
 
+
+/**
+ * Whether any selected skill has a recognized setup script.
+ *
+ * @param {MenuItem[]} items - Items selected for install/update.
+ * @returns {boolean}
+ */
+function hasSetupSkills(items) {
+  return items.some(item => item.type === 'skill' && skillHasSetup(ctx, item.name));
+}
+
+/**
+ * Prompts before running setup for selected skills that provide a recognized setup script.
+ *
+ * @param {MenuItem[]} items - Items selected for install/update.
+ * @returns {Promise<boolean>} Whether setup should run.
+ */
+async function confirmSetup(items) {
+  if (!hasSetupSkills(items)) return false;
+  const answer = await p.confirm({
+    message: 'Run setup scripts for selected skills that provide one? Setup runs in both .claude and .agents copies.',
+    initialValue: false,
+  });
+  if (p.isCancel(answer)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+  return Boolean(answer);
+}
+
+/**
+ * Removes recognized global install flags from positional arguments.
+ *
+ * @param {string[]} args - Raw command arguments after the command name.
+ * @returns {{rest: string[], runSetup: boolean}}
+ */
+function parseInstallFlags(args) {
+  let runSetup = false;
+  const rest = [];
+  for (const arg of args) {
+    if (arg === '--setup') runSetup = true;
+    else rest.push(arg);
+  }
+  return { rest, runSetup };
+}
+
 /**
  * Runs the interactive install/update flow (multiselect → apply). Exits the
  * process on a non-TTY stdin or user cancellation.
@@ -395,7 +446,13 @@ async function interactiveInstall(mode = 'install') {
     return;
   }
 
-  installItems(items, { replaceExisting: mode === 'update' });
+  const runSetup = await confirmSetup(items);
+  const ok = installItems(items, { replaceExisting: mode === 'update', runSetup });
+  if (!ok) {
+    p.outro(pc.red(`${mode === 'update' ? 'Update' : 'Install'} completed with errors.`));
+    process.exitCode = 1;
+    return;
+  }
   p.outro(mode === 'update' ? pc.green('Update complete.') : pc.green('Install complete.'));
 }
 
@@ -527,9 +584,13 @@ const HELP_TEXT = `Usage:
   npx td-ai-tools list                List available skills and agent packs
   npx td-ai-tools install             Interactive install
   npx td-ai-tools install --all       Install everything
+  npx td-ai-tools install --setup <name...>
+                                      Install and run recognized skill setup scripts
   npx td-ai-tools install <name...>   Install specific skills or agent packs
   npx td-ai-tools update              Interactive update (installed items in the catalog)
   npx td-ai-tools update --all        Update all installed items found in the catalog
+  npx td-ai-tools update --setup <name...>
+                                      Update and run recognized skill setup scripts
   npx td-ai-tools update <name...>    Update specific installed skills or agent packs
   npx td-ai-tools delete              Interactive delete
   npx td-ai-tools delete --all        Delete everything
@@ -581,17 +642,17 @@ async function main() {
   }
 
   if (cmd === 'install') {
-    const rest = args.slice(1);
+    const { rest, runSetup } = parseInstallFlags(args.slice(1));
     if (rest[0] === '--all') {
-      installItems(buildMenu());
+      if (!installItems(buildMenu(), { runSetup })) process.exitCode = 1;
     } else {
-      installItems(resolveNames(rest));
+      if (!installItems(resolveNames(rest), { runSetup })) process.exitCode = 1;
     }
     return;
   }
 
   if (cmd === 'update') {
-    const rest = args.slice(1);
+    const { rest, runSetup } = parseInstallFlags(args.slice(1));
     if (rest.length === 0) {
       await interactiveInstall('update');
       return;
@@ -602,9 +663,9 @@ async function main() {
         status('info', 'No installed skills or agent packs match the catalog.');
         return;
       }
-      installItems(menu, { replaceExisting: true });
+      if (!installItems(menu, { replaceExisting: true, runSetup })) process.exitCode = 1;
     } else {
-      installItems(resolveUpdateNames(rest), { replaceExisting: true });
+      if (!installItems(resolveUpdateNames(rest), { replaceExisting: true, runSetup })) process.exitCode = 1;
     }
     return;
   }

package/lib/installer.js

@@ -6,6 +6,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { copyDir } from './fs-utils.js';
 import { bundledAgentsIn } from './catalog.js';
 
@@ -24,6 +25,82 @@ import { bundledAgentsIn } from './catalog.js';
 /** @type {ReportFn} */
 const noop = () => {};
 
+/**
+ * Recognized setup commands, in priority order, relative to an installed skill.
+ * @type {{file: string, command: string, args: string[]}[]}
+ */
+const SKILL_SETUP_CANDIDATES = [
+  { file: 'setup.sh', command: 'bash', args: ['setup.sh'] },
+  { file: path.join('scripts', 'setup.sh'), command: 'bash', args: [path.join('scripts', 'setup.sh')] },
+  { file: 'package.json', command: 'npm', args: ['run', 'setup'] },
+];
+
+/**
+ * Finds the setup command for a skill directory, if one uses a recognized convention.
+ *
+ * @param {string} skillDir - Source or installed skill directory.
+ * @returns {({file: string, command: string, args: string[]}|null)} The setup command, or `null`.
+ */
+export function findSkillSetup(skillDir) {
+  for (const candidate of SKILL_SETUP_CANDIDATES) {
+    const filePath = path.join(skillDir, candidate.file);
+    if (!fs.existsSync(filePath)) continue;
+    if (candidate.file === 'package.json') {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (!pkg?.scripts?.setup) continue;
+      } catch {
+        continue;
+      }
+    }
+    return candidate;
+  }
+  return null;
+}
+
+/**
+ * Whether a catalog skill provides a setup command using a recognized convention.
+ *
+ * @param {Ctx} ctx
+ * @param {string} name - Skill name.
+ * @returns {boolean}
+ */
+export function skillHasSetup(ctx, name) {
+  return Boolean(findSkillSetup(path.join(ctx.skillsDir, name)));
+}
+
+/**
+ * Runs a skill setup command from the installed skill directory.
+ *
+ * @param {string} name - Skill name.
+ * @param {Target} target - The destination layout.
+ * @param {string} dest - Installed skill directory.
+ * @param {ReportFn} report
+ * @returns {boolean} Whether setup succeeded or no setup existed.
+ */
+function runSkillSetup(name, target, dest, report) {
+  const setup = findSkillSetup(dest);
+  if (!setup) return true;
+
+  report('step', `setup: ${name} running ${setup.command} ${setup.args.join(' ')} in ${target.root}/skills/${name}/`);
+  const result = spawnSync(setup.command, setup.args, {
+    cwd: dest,
+    stdio: 'inherit',
+    shell: false,
+  });
+  if (result.error) {
+    report('error', `setup: ${name} failed in ${target.root}/skills/${name}/: ${result.error.message}`);
+    return false;
+  }
+  if (result.status !== 0) {
+    report('error', `setup: ${name} failed in ${target.root}/skills/${name}/ with exit code ${result.status}`);
+    return false;
+  }
+  report('success', `setup: ${name} completed in ${target.root}/skills/${name}/`);
+  return true;
+}
+
+
 /**
  * Copies an item's bundled sub-agents into a target's `agents/` directory.
  *
@@ -52,10 +129,12 @@ function registerBundledAgents(ctx, target, srcDir, report) {
  * @param {string} name - Skill name.
  * @param {object} [options]
  * @param {boolean} [options.replaceExisting=false] - Overwrite an existing install (used by `update`).
+ * @param {boolean} [options.runSetup=false] - Run recognized setup scripts after each target copy.
  * @param {ReportFn} [options.report] - Progress sink.
- * @returns {boolean} `false` if the skill is not in the catalog, otherwise `true`.
+ * @returns {boolean} `false` if the skill is not in the catalog or setup fails, otherwise `true`.
  */
-export function installSkill(ctx, name, { replaceExisting = false, report = noop } = {}) {
+export function installSkill(ctx, name, { replaceExisting = false, runSetup = false, report = noop } = {}) {
+  let ok = true;
   const src = path.join(ctx.skillsDir, name);
   if (!fs.existsSync(src)) {
     report('error', `Skill "${name}" not found.`);
@@ -71,8 +150,9 @@ export function installSkill(ctx, name, { replaceExisting = false, report = noop
     copyDir(src, dest);
     report('success', `skill: ${name} ${replaceExisting ? 'updated' : 'installed'} → ${target.root}/skills/${name}/`);
     registerBundledAgents(ctx, target, src, report);
+    if (runSetup && !runSkillSetup(name, target, dest, report)) ok = false;
   }
-  return true;
+  return ok;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {