kushi-agents 3.4.1

package/src/main.mjs

@@ -0,0 +1,262 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_DEST,
+  CLAWPILOT_DEST_SUBPATH,
+  TARGET_VSCODE,
+  TARGET_CLAWPILOT,
+  CLAWPILOT_AGENT_SOURCE,
+  CLAWPILOT_SKILL_DEST,
+  PLUGIN_SOURCE_DIR,
+} from './constants.mjs';
+import { promptForDestination } from './prompt.mjs';
+import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
+import { mergeSettings } from './settings.mjs';
+import {
+  resolveProfile,
+  makeIncludeFilter,
+  writeInstalledManifest,
+} from './profile-resolver.mjs';
+
+/** Resolve the root of *this* npm package. */
+const PKG_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+
+function getVersion() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'),
+  );
+  return pkg.version;
+}
+
+function readDefaultProfile() {
+  const pj = JSON.parse(
+    fs.readFileSync(path.join(PKG_ROOT, PLUGIN_SOURCE_DIR, 'plugin.json'), 'utf-8'),
+  );
+  return pj.default_profile || 'standard';
+}
+
+function resolveProfileForInstall(profileName) {
+  const pluginJsonPath = path.join(PKG_ROOT, PLUGIN_SOURCE_DIR, 'plugin.json');
+  const name = profileName || readDefaultProfile();
+  return resolveProfile(pluginJsonPath, name);
+}
+
+/**
+ * Orchestrator: prompt -> copy -> settings -> summary.
+ * @param {{ dest?: string, force?: boolean, noSettings?: boolean, target?: string, profile?: string }} options
+ */
+export async function main(options = {}) {
+  const version = getVersion();
+  const target = options.target === TARGET_CLAWPILOT ? TARGET_CLAWPILOT : TARGET_VSCODE;
+
+  let resolved;
+  try {
+    resolved = resolveProfileForInstall(options.profile);
+  } catch (err) {
+    console.error(`\n  ${err.message}\n`);
+    process.exit(1);
+  }
+
+  console.log(
+    `\n  Kushi Agents Installer v${version}  [target: ${target}, profile: ${resolved.profile}]\n`,
+  );
+  console.log(`  Profile chain: ${resolved.chain.join(' -> ')}`);
+  console.log(`  ${resolved.description}\n`);
+
+  if (target === TARGET_CLAWPILOT) {
+    await installClawpilot(options, resolved, version);
+  } else {
+    await installVscode(options, resolved, version);
+  }
+}
+
+/**
+ * Install for VS Code Chat: copies assets into a workspace-local `.kushi/`
+ * folder and updates `.vscode/settings.json` so the chat surface picks them up.
+ */
+async function installVscode(options, resolved, version) {
+  const projectRoot = process.cwd();
+  const hasProjectMarker =
+    fs.existsSync(path.join(projectRoot, 'package.json')) ||
+    fs.existsSync(path.join(projectRoot, '.git'));
+
+  if (!hasProjectMarker) {
+    console.warn(
+      '  WARN: This directory does not look like a project root (no package.json or .git found). Proceeding anyway.\n',
+    );
+  }
+
+  let dest;
+  if (options.dest) {
+    dest = options.dest.replace(/\\/g, '/');
+    if (path.isAbsolute(dest)) {
+      console.error('\n  Please use a relative path (e.g., .kushi).\n');
+      process.exit(1);
+    }
+    dest = dest.replace(/\/+$/, '');
+    if (!dest) {
+      console.error('\n  Please provide a non-empty destination path.\n');
+      process.exit(1);
+    }
+    const resolvedPath = path.resolve(projectRoot, dest);
+    if (
+      !resolvedPath.startsWith(projectRoot + path.sep) &&
+      resolvedPath !== projectRoot
+    ) {
+      console.error('\n  Destination must be within the current project.\n');
+      process.exit(1);
+    }
+  } else {
+    dest = await promptForDestination(DEFAULT_DEST);
+  }
+
+  const fullDest = path.resolve(projectRoot, dest);
+  await confirmOverwriteIfExists(fullDest, dest, options.force);
+
+  const includeFilter = makeIncludeFilter(resolved);
+  const { copied, details } = copyAssets(PKG_ROOT, fullDest, includeFilter);
+
+  console.log(`  Copied ${copied} files to ${dest}/`);
+  for (const { dir, count } of details) {
+    if (count > 0) {
+      console.log(`    - ${dir}/ (${count} ${count === 1 ? 'file' : 'files'})`);
+    }
+  }
+
+  const manifestPath = writeInstalledManifest(fullDest, resolved, version);
+  console.log(`    - kushi-install.json (profile manifest)`);
+
+  if (!options.noSettings) {
+    const { created, keysAdded, keysUnchanged } = mergeSettings(
+      projectRoot,
+      dest,
+    );
+
+    console.log(
+      `\n  ${created ? 'Created' : 'Updated'} .vscode/settings.json`,
+    );
+    for (const key of keysAdded) {
+      console.log(`    - ${key} -> added`);
+    }
+    for (const key of keysUnchanged) {
+      console.log(`    - ${key} -> unchanged`);
+    }
+  } else {
+    console.log('\n  Skipped .vscode/settings.json (--no-settings)');
+  }
+
+  const { copied: projCopied, skipped: projSkipped } = copyProjectFiles(PKG_ROOT);
+  if (projCopied.length > 0) {
+    console.log('\n  Copied project files to .github/');
+    for (const f of projCopied) {
+      console.log(`    - ${f}`);
+    }
+  }
+  if (projSkipped.length > 0) {
+    for (const f of projSkipped) {
+      console.log(`    - ${f} -> unchanged (already exists)`);
+    }
+  }
+
+  printPostInstall(resolved, '@Kushi');
+}
+
+/**
+ * Install for Clawpilot CLI: copies assets into `~/.copilot/m-skills/kushi/`
+ * and writes a top-level `SKILL.md` (mirrored from `agents/kushi.agent.md`) so
+ * Clawpilot's skill discovery (`m_list_skills`) finds it as a single skill.
+ */
+async function installClawpilot(options, resolved, version) {
+  const home = os.homedir();
+  const fullDest = options.dest
+    ? path.resolve(options.dest)
+    : path.join(home, ...CLAWPILOT_DEST_SUBPATH.split('/'));
+
+  const displayDest = fullDest.startsWith(home + path.sep)
+    ? '~' + path.sep + path.relative(home, fullDest)
+    : fullDest;
+
+  await confirmOverwriteIfExists(fullDest, displayDest, options.force);
+
+  // If overwriting, wipe profile-dependent dirs first so an upgrade from
+  // standard -> core actually removes the standard-only skills.
+  if (fs.existsSync(fullDest) && options.force) {
+    for (const sub of ['skills', 'prompts', 'instructions', 'templates', 'reference-packs']) {
+      const p = path.join(fullDest, sub);
+      if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+    }
+  }
+
+  fs.mkdirSync(fullDest, { recursive: true });
+
+  const includeFilter = makeIncludeFilter(resolved);
+  const { copied, details } = copyAssets(PKG_ROOT, fullDest, includeFilter);
+
+  console.log(`  Copied ${copied} files to ${displayDest}\\`);
+  for (const { dir, count } of details) {
+    if (count > 0) {
+      console.log(`    - ${dir}/ (${count} ${count === 1 ? 'file' : 'files'})`);
+    }
+  }
+
+  writeInstalledManifest(fullDest, resolved, version);
+  console.log(`    - kushi-install.json (profile manifest)`);
+
+  // Mirror agents/kushi.agent.md as top-level SKILL.md for Clawpilot discovery.
+  const agentSrc = path.join(PKG_ROOT, PLUGIN_SOURCE_DIR, CLAWPILOT_AGENT_SOURCE);
+  const skillDst = path.join(fullDest, CLAWPILOT_SKILL_DEST);
+  if (fs.existsSync(agentSrc)) {
+    fs.cpSync(agentSrc, skillDst, { force: true });
+    console.log(`\n  Wrote ${CLAWPILOT_SKILL_DEST} (mirrored from ${CLAWPILOT_AGENT_SOURCE})`);
+  } else {
+    console.warn(`\n  WARN: ${CLAWPILOT_AGENT_SOURCE} not found in package — skipping SKILL.md.`);
+  }
+
+  printPostInstall(resolved, 'kushi');
+}
+
+function printPostInstall(resolved, prefix) {
+  console.log(`\n  Done. Profile "${resolved.profile}" installed. Available verbs:`);
+  for (const verb of resolved.verbs) {
+    console.log(`    ${prefix} ${verb} <project>`);
+  }
+  if (!resolved.verbs.includes('refresh')) {
+    console.log(
+      `\n  NOTE: 'refresh' / 'state' / 'bootstrap' are NOT available in profile "${resolved.profile}".`,
+    );
+    console.log(`        Re-install with --profile standard --force to enable them.`);
+  }
+  console.log('\n  Docs: https://gim-home.github.io/kushi/\n');
+}
+
+async function confirmOverwriteIfExists(fullDest, displayDest, force) {
+  if (!fs.existsSync(fullDest) || force) return;
+
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let overwrite;
+  try {
+    const answer = await rl.question(
+      `  ${displayDest} already exists. Overwrite? (Y/n): `,
+    );
+    overwrite = answer.trim().toLowerCase() !== 'n';
+  } catch {
+    process.exit(0);
+  } finally {
+    rl.close();
+  }
+
+  if (!overwrite) {
+    console.log('\n  Cancelled.\n');
+    process.exit(0);
+  }
+}

package/src/profile-resolver.mjs

@@ -0,0 +1,168 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolve a profile name into the concrete asset set to install.
+ *
+ * Walks the `extends:` chain in plugin.json profiles and unions the
+ * skills / prompts / instructions / templates / verbs lists.
+ *
+ * @param {string} pluginJsonPath - absolute path to plugin/plugin.json
+ * @param {string} profileName    - one of the keys under "profiles"
+ * @returns {{
+ *   profile: string,
+ *   chain: string[],
+ *   skills: string[],
+ *   prompts: string[],
+ *   instructions: string[] | '*',
+ *   templates: string[],
+ *   referencePacks: string[],
+ *   verbs: string[],
+ *   description: string
+ * }}
+ */
+export function resolveProfile(pluginJsonPath, profileName) {
+  const raw = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf-8'));
+  const profiles = raw.profiles || {};
+
+  if (!profiles[profileName]) {
+    const available = Object.keys(profiles).join(', ') || '(none defined)';
+    throw new Error(
+      `Unknown profile "${profileName}". Available: ${available}.`,
+    );
+  }
+
+  // Walk extends chain from root down so child overrides win on description.
+  const chain = [];
+  let cursor = profileName;
+  const guard = new Set();
+  while (cursor) {
+    if (guard.has(cursor)) {
+      throw new Error(`Circular extends in profile "${cursor}".`);
+    }
+    guard.add(cursor);
+    chain.unshift(cursor);
+    cursor = profiles[cursor]?.extends;
+  }
+
+  const merged = {
+    skills: new Set(),
+    prompts: new Set(),
+    instructions: null, // '*' means all
+    templates: new Set(),
+    referencePacks: new Set(),
+    verbs: new Set(),
+  };
+
+  for (const name of chain) {
+    const p = profiles[name];
+    for (const s of p.skills || []) merged.skills.add(s);
+    for (const s of p.prompts || []) merged.prompts.add(s);
+    for (const s of p.templates || []) merged.templates.add(s);
+    for (const s of p.reference_packs || []) merged.referencePacks.add(s);
+    for (const s of p.verbs || []) merged.verbs.add(s);
+    if (p.instructions === '*' || merged.instructions === '*') {
+      merged.instructions = '*';
+    } else if (Array.isArray(p.instructions)) {
+      if (!merged.instructions) merged.instructions = new Set();
+      for (const s of p.instructions) merged.instructions.add(s);
+    }
+  }
+
+  return {
+    profile: profileName,
+    chain,
+    description: profiles[profileName].description || '',
+    skills: [...merged.skills],
+    prompts: [...merged.prompts],
+    instructions:
+      merged.instructions === '*' || merged.instructions === null
+        ? '*'
+        : [...merged.instructions],
+    templates: [...merged.templates],
+    referencePacks: [...merged.referencePacks],
+    verbs: [...merged.verbs],
+  };
+}
+
+/**
+ * Build the include-set used by copyDirFiltered: a function that takes a
+ * relative path like "skills/pull-email/SKILL.md" and returns true if it
+ * should be copied for the given resolved profile.
+ *
+ * @param {ReturnType<typeof resolveProfile>} resolved
+ */
+export function makeIncludeFilter(resolved) {
+  const skillSet = new Set(resolved.skills);
+  const promptSet = new Set(resolved.prompts);
+  const templateSet = new Set(resolved.templates);
+  const packSet = new Set(resolved.referencePacks);
+  const allInstr = resolved.instructions === '*';
+  const instrSet = allInstr ? null : new Set(resolved.instructions);
+
+  return function include(assetDir, relPath) {
+    // assetDir is one of: agents, instructions, prompts, skills, templates
+    if (assetDir === 'agents') return true;
+
+    if (assetDir === 'skills') {
+      const top = relPath.split(/[\\/]/)[0];
+      return skillSet.has(top);
+    }
+
+    if (assetDir === 'prompts') {
+      // e.g. "bootstrap.prompt.md" -> match "bootstrap"
+      const base = relPath.split(/[\\/]/)[0];
+      const stem = base.replace(/\.prompt\.md$/, '');
+      return promptSet.has(stem);
+    }
+
+    if (assetDir === 'instructions') {
+      if (allInstr) return true;
+      const base = relPath.split(/[\\/]/)[0];
+      const stem = base.replace(/\.instructions\.md$/, '');
+      return instrSet.has(stem);
+    }
+
+    if (assetDir === 'templates') {
+      const top = relPath.split(/[\\/]/)[0];
+      return templateSet.has(top);
+    }
+
+    if (assetDir === 'reference-packs') {
+      // Always include the top-level README.md doctrine file.
+      if (!relPath.includes(path.sep) && !relPath.includes('/') && /^README\.md$/i.test(relPath)) {
+        return true;
+      }
+      const top = relPath.split(/[\\/]/)[0];
+      return packSet.has(top);
+    }
+
+    return true;
+  };
+}
+
+/**
+ * Write a slim manifest into the install destination so the host (and
+ * self-check) knows which profile is installed.
+ *
+ * @param {string} destAbsolute
+ * @param {ReturnType<typeof resolveProfile>} resolved
+ * @param {string} version
+ */
+export function writeInstalledManifest(destAbsolute, resolved, version) {
+  const file = path.join(destAbsolute, 'kushi-install.json');
+  const manifest = {
+    profile: resolved.profile,
+    chain: resolved.chain,
+    version,
+    skills: resolved.skills.sort(),
+    prompts: resolved.prompts.sort(),
+    instructions: resolved.instructions === '*' ? '*' : resolved.instructions.sort(),
+    templates: resolved.templates.sort(),
+    reference_packs: [...(resolved.referencePacks || [])].sort(),
+    verbs: resolved.verbs.sort(),
+    installed_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
+  return file;
+}

package/src/prompt.mjs

@@ -0,0 +1,42 @@
+import { createInterface } from 'node:readline/promises';
+import path from 'node:path';
+
+/**
+ * Prompt the user for a destination directory.
+ * @param {string} defaultDest
+ * @returns {Promise<string>}
+ */
+export async function promptForDestination(defaultDest) {
+  const { stdin: input, stdout: output } = await import('node:process');
+  const rl = createInterface({ input, output });
+
+  rl.on('close', () => {});
+
+  let dest;
+  try {
+    const answer = await rl.question(
+      `  Where should Kushi assets be installed? (${defaultDest}): `,
+    );
+    dest = answer.trim() || defaultDest;
+  } catch {
+    process.exit(0);
+  } finally {
+    rl.close();
+  }
+
+  return validatePath(dest);
+}
+
+function validatePath(raw) {
+  if (path.isAbsolute(raw)) {
+    console.error('\n  Please use a relative path (e.g., .kushi).\n');
+    process.exit(1);
+  }
+  const resolved = path.resolve(process.cwd(), raw);
+  const root = process.cwd();
+  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+    console.error('\n  Destination must be within the current project.\n');
+    process.exit(1);
+  }
+  return raw.replace(/\\/g, '/').replace(/\/+$/, '');
+}

package/src/settings.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { modify, applyEdits, parse, printParseErrorCode } from 'jsonc-parser';
+import { SETTINGS_MAP } from './constants.mjs';
+
+/**
+ * Merge Nova settings into .vscode/settings.json (JSONC-safe).
+ * Creates the file and directory if they don't exist.
+ * Additive-only: never removes existing entries.
+ *
+ * @param {string} projectRoot – the user's project root (cwd)
+ * @param {string} destination – relative destination path (e.g. ".nova")
+ * @returns {{ created: boolean, keysAdded: string[], keysUnchanged: string[] }}
+ */
+export function mergeSettings(projectRoot, destination) {
+  const vscodeDir = path.join(projectRoot, '.vscode');
+  const settingsPath = path.join(vscodeDir, 'settings.json');
+
+  // Ensure .vscode/ exists
+  fs.mkdirSync(vscodeDir, { recursive: true });
+
+  let content;
+  let created = false;
+
+  if (fs.existsSync(settingsPath)) {
+    content = fs.readFileSync(settingsPath, 'utf-8');
+
+    // Validate the JSONC is parseable
+    /** @type {import('jsonc-parser').ParseError[]} */
+    const errors = [];
+    parse(content, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+      const first = errors[0];
+      // Compute line number from offset
+      const line = content.slice(0, first.offset).split('\n').length;
+      console.error(
+        `\n  ✘ Your settings.json has a syntax error at line ${line} (${printParseErrorCode(first.error)}). Fix it and re-run.\n`,
+      );
+      process.exit(1);
+    }
+  } else {
+    content = '{}';
+    created = true;
+  }
+
+  const keysAdded = [];
+  const keysUnchanged = [];
+
+  for (const [settingsKey, subdir] of Object.entries(SETTINGS_MAP)) {
+    // Always use forward slashes in settings paths
+    const entryPath = [destination, subdir].join('/');
+
+    // Check if the exact path entry already exists
+    const parsed = parse(content, undefined, { allowTrailingComma: true });
+    const existing = parsed?.[settingsKey];
+
+    if (existing && typeof existing === 'object' && existing[entryPath] === true) {
+      keysUnchanged.push(settingsKey);
+      continue;
+    }
+
+    // Use jsonc-parser's modify to add/merge the entry while preserving comments
+    const edits = modify(content, [settingsKey, entryPath], true, {
+      formattingOptions: {
+        tabSize: 2,
+        insertSpaces: true,
+        eol: '\n',
+      },
+    });
+    content = applyEdits(content, edits);
+    keysAdded.push(settingsKey);
+  }
+
+  fs.writeFileSync(settingsPath, content, 'utf-8');
+
+  return { created, keysAdded, keysUnchanged };
+}