takomi 2.1.26 → 2.1.28

package/src/harness.js

@@ -1,6 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
+import crypto from 'crypto';
 import pc from 'picocolors';
 
 // ─── Cross-Platform Home Directory ───────────────────────────────────────────
@@ -169,33 +170,122 @@ export function printHarnessStatus(detected) {
  * @param {string} label       - Human-readable label for logging
  * @returns {Promise<number>}  - Number of items copied
  */
-export async function syncDirectory(sourcePath, targetPath, label = '') {
-  if (!targetPath) return 0;
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+async function hashPath(targetPath) {
+  if (!await fs.pathExists(targetPath)) return null;
+  const stat = await fs.stat(targetPath);
+  if (stat.isFile()) return sha256(await fs.readFile(targetPath));
+
+  const entries = [];
+  async function walk(current, prefix = '') {
+    const names = (await fs.readdir(current)).sort();
+    for (const name of names) {
+      const full = path.join(current, name);
+      const rel = path.join(prefix, name).replace(/\\/g, '/');
+      const st = await fs.stat(full);
+      if (st.isDirectory()) {
+        entries.push(`dir:${rel}`);
+        await walk(full, rel);
+      } else {
+        entries.push(`file:${rel}:${sha256(await fs.readFile(full))}`);
+      }
+    }
+  }
+  await walk(targetPath);
+  return sha256(entries.join('\n'));
+}
+
+function normalizeOwnedMap(value) {
+  if (!value || typeof value !== 'object') return {};
+  const normalized = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (typeof entry === 'string') normalized[name] = { hash: entry };
+    else if (entry?.hash) normalized[name] = entry;
+  }
+  return normalized;
+}
+
+/**
+ * Syncs a directory to a target path. When ownership is supplied, it also
+ * prunes previous Takomi-owned items that are no longer in the source while
+ * preserving manual or modified files.
+ */
+export async function syncDirectory(sourcePath, targetPath, label = '', options = {}) {
+  if (!targetPath) return options.returnDetails ? { copied: 0, pruned: 0, preservedManual: [], preservedModified: [], owned: {} } : 0;
 
   try {
     await fs.ensureDir(targetPath);
 
-    const items = await fs.readdir(sourcePath);
-    let count = 0;
+    const items = (await fs.readdir(sourcePath)).sort();
+    const itemSet = new Set(items);
+    const previousOwned = normalizeOwnedMap(options.owned);
+    const nextOwned = {};
+    const preservedManual = [];
+    const preservedModified = [];
+    let copied = 0;
+    let pruned = 0;
+
+    if (options.prune && Object.keys(previousOwned).length > 0) {
+      for (const [item, ownedEntry] of Object.entries(previousOwned)) {
+        if (itemSet.has(item)) continue;
+        const dest = path.join(targetPath, item);
+        if (!await fs.pathExists(dest)) continue;
+        const currentHash = await hashPath(dest);
+        if (currentHash && currentHash === ownedEntry.hash) {
+          await fs.remove(dest);
+          pruned++;
+        } else {
+          preservedModified.push(item);
+          nextOwned[item] = ownedEntry;
+        }
+      }
+    }
 
     for (const item of items) {
       const src = path.join(sourcePath, item);
       const dest = path.join(targetPath, item);
+      const previous = previousOwned[item];
+
+      if (await fs.pathExists(dest)) {
+        const currentHash = await hashPath(dest);
+        if (options.preserveManual && !previous) {
+          preservedManual.push(item);
+          continue;
+        }
+        if (previous?.hash && currentHash && currentHash !== previous.hash) {
+          preservedModified.push(item);
+          nextOwned[item] = previous;
+          continue;
+        }
+        await fs.remove(dest);
+      }
 
       await fs.copy(src, dest, { overwrite: true });
-      count++;
+      nextOwned[item] = {
+        hash: await hashPath(dest),
+        targetPath: dest,
+        syncedAt: new Date().toISOString(),
+      };
+      copied++;
     }
 
     if (label) {
-      console.log(pc.green(`  ✔ ${label} (${count} items)`));
+      const suffix = pruned ? `, removed ${pruned}` : '';
+      console.log(pc.green(`  ✔ ${label} (${copied} items${suffix})`));
+      if (preservedManual.length) console.log(pc.yellow(`    Preserved manual items: ${preservedManual.join(', ')}`));
+      if (preservedModified.length) console.log(pc.yellow(`    Preserved modified Takomi-owned items: ${preservedModified.join(', ')}`));
     }
 
-    return count;
+    const details = { copied, pruned, preservedManual, preservedModified, owned: Object.fromEntries(Object.entries(nextOwned).sort(([a], [b]) => a.localeCompare(b))) };
+    return options.returnDetails ? details : copied;
   } catch (error) {
     if (label) {
       console.log(pc.red(`  ✗ ${label}: ${error.message}`));
     }
-    return 0;
+    return options.returnDetails ? { copied: 0, pruned: 0, preservedManual: [], preservedModified: [], owned: {} } : 0;
   }
 }
 
@@ -238,29 +328,55 @@ export async function syncFile(sourceFile, targetPaths, label = '') {
  * @param {string} storePath - Path to the global store (~/.takomi/)
  * @returns {Promise<{skills: number, workflows: number, yamls: number}>}
  */
-export async function syncToHarness(harness, storePath) {
-  const results = { skills: 0, workflows: 0, yamls: 0 };
+export async function syncToHarness(harness, storePath, options = {}) {
+  const results = { skills: 0, workflows: 0, yamls: 0, owned: { skills: {}, workflows: {} } };
+  const harnessOwned = options.owned?.[harness.id] || {};
+  const useOwnership = Boolean(options.useOwnership);
 
   console.log(pc.cyan(`\n  📡 Syncing to ${harness.name}...`));
 
   // Skills
   const skillsStore = path.join(storePath, 'skills');
   if (harness.targets.skills && await fs.pathExists(skillsStore)) {
-    results.skills = await syncDirectory(
+    const skillResult = await syncDirectory(
       skillsStore,
       harness.targets.skills,
-      `Skills → ${harness.name}`
+      `Skills → ${harness.name}`,
+      {
+        owned: harnessOwned.skills,
+        preserveManual: useOwnership,
+        prune: useOwnership,
+        returnDetails: useOwnership,
+      },
     );
+    if (useOwnership) {
+      results.skills = skillResult.copied;
+      results.owned.skills = skillResult.owned;
+    } else {
+      results.skills = skillResult;
+    }
   }
 
   // Workflows
   const workflowsStore = path.join(storePath, 'workflows');
   if (harness.targets.workflows && await fs.pathExists(workflowsStore)) {
-    results.workflows = await syncDirectory(
+    const workflowResult = await syncDirectory(
       workflowsStore,
       harness.targets.workflows,
-      `Workflows → ${harness.name}`
+      `Workflows → ${harness.name}`,
+      {
+        owned: harnessOwned.workflows,
+        preserveManual: useOwnership,
+        prune: useOwnership,
+        returnDetails: useOwnership,
+      },
     );
+    if (useOwnership) {
+      results.workflows = workflowResult.copied;
+      results.owned.workflows = workflowResult.owned;
+    } else {
+      results.workflows = workflowResult;
+    }
   }
 
   // YAMLs (KiloCode custom_modes.yaml dual-path)
@@ -283,11 +399,11 @@ export async function syncToHarness(harness, storePath) {
  * @param {string} storePath - Path to the global store (~/.takomi/)
  * @returns {Promise<object>} - Summary of sync results
  */
-export async function syncToAllHarnesses(harnesses, storePath) {
+export async function syncToAllHarnesses(harnesses, storePath, options = {}) {
   const summary = {};
 
   for (const harness of harnesses) {
-    summary[harness.id] = await syncToHarness(harness, storePath);
+    summary[harness.id] = await syncToHarness(harness, storePath, options);
   }
 
   return summary;

package/src/pi-harness.js

@@ -220,6 +220,9 @@ export async function ensurePiInstalled() {
   }
 
   const attempts = [
+    { command: 'npm', args: ['install', '-g', '@earendil-works/pi-coding-agent'] },
+    { command: 'npm.cmd', args: ['install', '-g', '@earendil-works/pi-coding-agent'] },
+    // Legacy fallback for older environments that still publish under the original namespace.
     { command: 'npm', args: ['install', '-g', '@mariozechner/pi-coding-agent'] },
     { command: 'npm.cmd', args: ['install', '-g', '@mariozechner/pi-coding-agent'] },
   ];
@@ -301,19 +304,23 @@ export async function updatePiManagedPackages() {
   const pi = await detectPiCommand();
   if (!pi.installed) return { ok: false, changed: false, report: 'Pi is not installed.' };
 
+  // `pi update` reconciles every package listed in Pi settings, including
+  // user-installed npm/git/local packages. Keep this broad so Takomi refresh
+  // updates old, new, custom, and optional feature packages without needing to
+  // know their names ahead of time.
   const command = pi.path || 'pi';
   const result = runCommand(command, ['update']);
   const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
   return {
     ok: result.status === 0,
     changed: result.status === 0,
-    report: output || (result.status === 0 ? 'Pi managed packages are up to date.' : 'pi update failed.'),
+    report: output || (result.status === 0 ? 'All Pi-managed packages are up to date.' : 'pi update failed.'),
   };
 }
 
 export function printPiManagedPackageUpdateResult(result) {
   if (result.ok) {
-    console.log(pc.green('✔ Updated Pi-managed packages'));
+    console.log(pc.green('✔ Updated all Pi-managed packages'));
     if (result.report) console.log(pc.dim(result.report.split(/\r?\n/).slice(-8).join('\n')));
     return;
   }
@@ -342,18 +349,32 @@ export async function inspectPiHarnessEnvironment(cwd = process.cwd()) {
   };
 }
 
+function printFirstRunGuidance(reason) {
+  console.log(pc.magenta('\n🎯 Welcome to Takomi\n'));
+  if (reason) console.log(pc.yellow(reason));
+  console.log(pc.white('\nRecommended first step:'));
+  console.log(pc.cyan('  takomi setup pi'));
+  console.log(pc.dim('    Set up the Pi-native Takomi harness.'));
+  console.log(pc.white('\nOptional setup:'));
+  console.log(pc.dim('  takomi setup pi-features  Add optional Pi feature packs'));
+  console.log(pc.dim('  takomi setup skills       Install global Takomi skills'));
+  console.log(pc.dim('  takomi setup all          Set up Pi + skills'));
+  console.log(pc.white('\nDiagnostics and help:'));
+  console.log(pc.dim('  takomi doctor             Check installation health'));
+  console.log(pc.dim('  takomi status             Show connected harnesses/toolkit status'));
+  console.log(pc.dim('  takomi --help             Show all commands\n'));
+}
+
 export async function launchTakomiHarness(cwd = process.cwd()) {
   const report = await inspectPiHarnessEnvironment(cwd);
 
   if (!report.pi.installed) {
-    console.log(pc.red('Pi is not installed.'));
-    console.log(pc.dim('Run: takomi install pi'));
+    printFirstRunGuidance('Pi is not installed yet.');
     return 1;
   }
 
   if (!report.installed.runtimeInstalled || !report.installed.subagentsInstalled) {
-    console.log(pc.red('Takomi Pi harness is not fully installed.'));
-    console.log(pc.dim('Run: takomi install pi'));
+    printFirstRunGuidance('Takomi Pi harness is not fully installed yet.');
     return 1;
   }
 

package/src/pi-optional-features.js

@@ -0,0 +1,195 @@
+import fs from 'fs-extra';
+import { spawnSync } from 'child_process';
+import prompts from 'prompts';
+import pc from 'picocolors';
+import { detectPiCommand, getPiGlobalTargets } from './pi-harness.js';
+
+export const TAKOMI_PI_OPTIONAL_FEATURES = [
+  {
+    id: 'takomi-interview',
+    title: 'Takomi Interview',
+    packageSpec: 'npm:@juicesharp/rpiv-ask-user-question',
+    npmPackage: '@juicesharp/rpiv-ask-user-question',
+    selectedByDefault: true,
+    recommended: true,
+    description: 'Structured model questions for Genesis/design clarification. Default Takomi add-on.',
+  },
+  {
+    id: 'takomi-todo',
+    title: 'Takomi Todo',
+    packageSpec: 'npm:@juicesharp/rpiv-todo',
+    npmPackage: '@juicesharp/rpiv-todo',
+    selectedByDefault: false,
+    recommended: false,
+    description: 'Live model todo overlay. Optional while it is being tested.',
+  },
+  {
+    id: 'takomi-browser-qa',
+    title: 'Takomi Browser QA',
+    packageSpec: 'npm:pi-chrome',
+    npmPackage: 'pi-chrome',
+    selectedByDefault: false,
+    recommended: false,
+    description: 'Chrome/browser automation for UI QA and authenticated web workflows.',
+  },
+  {
+    id: 'takomi-doc-preview',
+    title: 'Takomi Doc Preview',
+    packageSpec: 'npm:pi-markdown-preview',
+    npmPackage: 'pi-markdown-preview',
+    selectedByDefault: false,
+    recommended: false,
+    description: 'Markdown/LaTeX/browser/PDF previews for Takomi docs and handoffs.',
+  },
+];
+
+function runCommand(command, args) {
+  return spawnSync(command, args, { stdio: 'pipe', encoding: 'utf8', shell: process.platform === 'win32' });
+}
+
+function packageIdentity(packageSpec) {
+  if (!packageSpec.startsWith('npm:')) return packageSpec;
+  const withoutPrefix = packageSpec.slice(4);
+  if (withoutPrefix.startsWith('@')) {
+    const parts = withoutPrefix.split('@');
+    return `${parts[0]}@${parts[1]}`;
+  }
+  return withoutPrefix.split('@')[0];
+}
+
+function packageEntrySource(entry) {
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object' && typeof entry.source === 'string') return entry.source;
+  return undefined;
+}
+
+function packageMatches(entry, packageSpec) {
+  const source = packageEntrySource(entry);
+  if (!source) return false;
+  if (source === packageSpec) return true;
+  if (!source.startsWith('npm:') || !packageSpec.startsWith('npm:')) return false;
+  return packageIdentity(source) === packageIdentity(packageSpec);
+}
+
+async function readGlobalPiSettings() {
+  try {
+    return await fs.readJson(getPiGlobalTargets().settings);
+  } catch {
+    return {};
+  }
+}
+
+export async function getInstalledPiPackageSpecs() {
+  const settings = await readGlobalPiSettings();
+  return Array.isArray(settings.packages) ? settings.packages : [];
+}
+
+export async function isPiPackageInstalled(packageSpec) {
+  const packages = await getInstalledPiPackageSpecs();
+  return packages.some((entry) => packageMatches(entry, packageSpec));
+}
+
+export async function installPiPackage(packageSpec) {
+  const pi = await detectPiCommand();
+  if (!pi.installed) return { ok: false, changed: false, report: 'Pi is not installed.' };
+
+  if (await isPiPackageInstalled(packageSpec)) {
+    return { ok: true, changed: false, report: `${packageSpec} already listed in Pi settings.` };
+  }
+
+  const command = pi.path || 'pi';
+  const result = runCommand(command, ['install', packageSpec]);
+  const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  return {
+    ok: result.status === 0,
+    changed: result.status === 0,
+    report: output || (result.status === 0 ? `Installed ${packageSpec}.` : `pi install ${packageSpec} failed.`),
+  };
+}
+
+export async function installPiOptionalFeatures(featureIds) {
+  const selected = TAKOMI_PI_OPTIONAL_FEATURES.filter((feature) => featureIds.includes(feature.id));
+  const results = [];
+  for (const feature of selected) {
+    const result = await installPiPackage(feature.packageSpec);
+    results.push({ feature, ...result });
+  }
+  return results;
+}
+
+export function printPiOptionalFeatureResults(results) {
+  if (!results.length) {
+    console.log(pc.dim('  Optional Pi features skipped.'));
+    return;
+  }
+
+  for (const result of results) {
+    const icon = result.ok ? (result.changed ? pc.green('✔') : pc.dim('•')) : pc.yellow('⚠');
+    const action = result.ok ? (result.changed ? 'Installed' : 'Already installed') : 'Could not install';
+    console.log(`${icon} ${action} ${result.feature.title} (${result.feature.packageSpec})`);
+    if (result.report) console.log(pc.dim(result.report.split(/\r?\n/).slice(-4).join('\n')));
+  }
+}
+
+export async function selectPiOptionalFeatures(options = {}) {
+  const { interactive = true } = options;
+  if (!interactive) {
+    return TAKOMI_PI_OPTIONAL_FEATURES
+      .filter((feature) => feature.selectedByDefault)
+      .map((feature) => feature.id);
+  }
+
+  const modeResponse = await prompts({
+    type: 'select',
+    name: 'mode',
+    message: 'Optional Pi features to install?',
+    choices: [
+      { title: 'Recommended defaults', value: 'recommended', description: 'Takomi Interview now; keep other packs optional' },
+      { title: 'Select all', value: 'all', description: 'Install every official optional Takomi Pi pack' },
+      { title: 'Manual selection', value: 'manual', description: 'Choose individual optional packages' },
+      { title: 'Skip optional features', value: 'skip', description: 'Only install the Takomi core harness' },
+    ],
+    initial: 0,
+  });
+
+  if (!modeResponse.mode || modeResponse.mode === 'skip') return [];
+  if (modeResponse.mode === 'all') return TAKOMI_PI_OPTIONAL_FEATURES.map((feature) => feature.id);
+  if (modeResponse.mode === 'recommended') {
+    return TAKOMI_PI_OPTIONAL_FEATURES
+      .filter((feature) => feature.selectedByDefault || feature.recommended)
+      .map((feature) => feature.id);
+  }
+
+  const manualResponse = await prompts({
+    type: 'multiselect',
+    name: 'features',
+    message: 'Select optional Takomi Pi feature packs:',
+    choices: TAKOMI_PI_OPTIONAL_FEATURES.map((feature) => ({
+      title: feature.title,
+      value: feature.id,
+      selected: feature.selectedByDefault,
+      description: `${feature.description} (${feature.packageSpec})`,
+    })),
+    hint: '- Space to select. Press a to toggle all. Return to submit',
+  });
+
+  return manualResponse.features || [];
+}
+
+export async function offerPiOptionalFeatures(options = {}) {
+  const featureIds = await selectPiOptionalFeatures(options);
+  const results = await installPiOptionalFeatures(featureIds);
+  printPiOptionalFeatureResults(results);
+  return results;
+}
+
+export function renderPiOptionalFeatureCatalog() {
+  return TAKOMI_PI_OPTIONAL_FEATURES.map((feature) => ({
+    id: feature.id,
+    title: feature.title,
+    packageSpec: feature.packageSpec,
+    selectedByDefault: feature.selectedByDefault,
+    recommended: feature.recommended,
+    description: feature.description,
+  }));
+}

package/src/postinstall.js

@@ -0,0 +1,27 @@
+try {
+  if (process.env.TAKOMI_SUPPRESS_POSTINSTALL === '1') process.exit(0);
+  if (process.env.CI === 'true' || process.env.CI === '1') process.exit(0);
+
+  const lines = [
+    '',
+    '🎯 Takomi installed.',
+    '',
+    'Recommended next steps:',
+    '  takomi setup pi          Set up the Pi-native Takomi harness',
+    '  takomi setup pi-features Add optional Pi feature packs',
+    '  takomi setup skills      Install global Takomi skills',
+    '  takomi setup all         Set up Pi + skills',
+    '',
+    'Useful commands:',
+    '  takomi doctor            Check installation health',
+    '  takomi status            Show connected harnesses/toolkit status',
+    '  takomi refresh           Update Takomi, Pi assets, skills, and Pi packages',
+    '  takomi --help            Show all commands',
+    '',
+    'Then run `takomi` from inside a project.',
+    '',
+  ];
+  console.log(lines.join('\n'));
+} catch {
+  // Postinstall guidance must never break package installation.
+}