@alavida/agentpack 0.1.1 → 0.1.3

package/src/domain/skills/skill-provenance.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  readBuildState as readBuildStateRecord,
+  writeBuildState as writeBuildStateRecord,
+} from '../../infrastructure/fs/build-state-repository.js';
+
+export function hashFile(filePath) {
+  const digest = createHash('sha256').update(readFileSync(filePath)).digest('hex');
+  return `sha256:${digest}`;
+}
+
+export function readBuildState(repoRoot) {
+  return readBuildStateRecord(repoRoot);
+}
+
+export function writeBuildState(repoRoot, state) {
+  writeBuildStateRecord(repoRoot, state);
+}
+
+export function compareRecordedSources(repoRoot, record) {
+  const changes = [];
+  const recordedSources = record.sources || {};
+
+  for (const [sourcePath, sourceRecord] of Object.entries(recordedSources)) {
+    const absoluteSourcePath = join(repoRoot, sourcePath);
+    const currentHash = hashFile(absoluteSourcePath);
+    const recordedHash = sourceRecord.hash;
+
+    if (currentHash !== recordedHash) {
+      changes.push({
+        path: sourcePath,
+        recorded: recordedHash,
+        current: currentHash,
+      });
+    }
+  }
+
+  return changes;
+}
+
+export function buildStateRecordForPackageDir(repoRoot, packageDir, {
+  parseSkillFrontmatterFile,
+  readPackageMetadata,
+  normalizeDisplayPath,
+} = {}) {
+  const skillFile = join(packageDir, 'SKILL.md');
+  const metadata = parseSkillFrontmatterFile(skillFile);
+  const packageMetadata = readPackageMetadata(packageDir);
+  const sources = {};
+
+  for (const sourcePath of metadata.sources) {
+    sources[sourcePath] = {
+      hash: hashFile(join(repoRoot, sourcePath)),
+    };
+  }
+
+  return {
+    packageName: packageMetadata.packageName,
+    record: {
+      package_version: packageMetadata.packageVersion,
+      skill_path: normalizeDisplayPath(repoRoot, packageDir),
+      skill_file: normalizeDisplayPath(repoRoot, skillFile),
+      sources,
+      requires: metadata.requires,
+    },
+  };
+}

package/src/infrastructure/fs/build-state-repository.js

@@ -0,0 +1,16 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readBuildState(repoRoot) {
+  const buildStatePath = join(repoRoot, '.agentpack', 'build-state.json');
+  if (!existsSync(buildStatePath)) {
+    return { version: 1, skills: {} };
+  }
+
+  return JSON.parse(readFileSync(buildStatePath, 'utf-8'));
+}
+
+export function writeBuildState(repoRoot, state) {
+  mkdirSync(join(repoRoot, '.agentpack'), { recursive: true });
+  writeFileSync(join(repoRoot, '.agentpack', 'build-state.json'), JSON.stringify(state, null, 2) + '\n');
+}

package/src/infrastructure/fs/install-state-repository.js

@@ -0,0 +1,16 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readInstallState(repoRoot) {
+  const installStatePath = join(repoRoot, '.agentpack', 'install.json');
+  if (!existsSync(installStatePath)) {
+    return { version: 1, installs: {} };
+  }
+
+  return JSON.parse(readFileSync(installStatePath, 'utf-8'));
+}
+
+export function writeInstallState(repoRoot, state) {
+  mkdirSync(join(repoRoot, '.agentpack'), { recursive: true });
+  writeFileSync(join(repoRoot, '.agentpack', 'install.json'), JSON.stringify(state, null, 2) + '\n');
+}

package/src/infrastructure/runtime/materialize-skills.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, rmSync, symlinkSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { writeInstallState } from '../fs/install-state-repository.js';
+
+function ensureDir(pathValue) {
+  mkdirSync(pathValue, { recursive: true });
+}
+
+export function removePathIfExists(pathValue) {
+  rmSync(pathValue, { recursive: true, force: true });
+}
+
+export function ensureSkillLink(repoRoot, baseDir, skillName, skillDir, normalizeDisplayPath) {
+  const skillsDir = join(repoRoot, baseDir, 'skills');
+  ensureDir(skillsDir);
+  const linkPath = join(skillsDir, skillName);
+  removePathIfExists(linkPath);
+  symlinkSync(skillDir, linkPath, 'dir');
+  return normalizeDisplayPath(repoRoot, linkPath);
+}
+
+export function removeSkillLinks(repoRoot, name, normalizeDisplayPath) {
+  const removed = [];
+  for (const pathValue of [
+    join(repoRoot, '.claude', 'skills', name),
+    join(repoRoot, '.agents', 'skills', name),
+  ]) {
+    if (!existsSync(pathValue)) continue;
+    removePathIfExists(pathValue);
+    removed.push(normalizeDisplayPath(repoRoot, pathValue));
+  }
+  return removed;
+}
+
+export function removeSkillLinksByNames(repoRoot, names, normalizeDisplayPath) {
+  const removed = [];
+  for (const name of names) {
+    removed.push(...removeSkillLinks(repoRoot, name, normalizeDisplayPath));
+  }
+  return [...new Set(removed)];
+}
+
+function ensureSymlink(targetPath, linkPath) {
+  removePathIfExists(linkPath);
+  mkdirSync(dirname(linkPath), { recursive: true });
+  symlinkSync(targetPath, linkPath, 'dir');
+}
+
+export function buildInstallRecord(repoRoot, packageDir, directTargetMap, {
+  parseSkillFrontmatterFile,
+  readPackageMetadata,
+  normalizeRelativePath,
+} = {}) {
+  const packageMetadata = readPackageMetadata(packageDir);
+  if (!packageMetadata.packageName) return null;
+
+  const skillMetadata = parseSkillFrontmatterFile(join(packageDir, 'SKILL.md'));
+  const skillDirName = skillMetadata.name;
+  const materializations = [];
+
+  const claudeTargetAbs = join(repoRoot, '.claude', 'skills', skillDirName);
+  ensureSymlink(packageDir, claudeTargetAbs);
+  materializations.push({
+    target: normalizeRelativePath(relative(repoRoot, claudeTargetAbs)),
+    mode: 'symlink',
+  });
+
+  const agentsTargetAbs = join(repoRoot, '.agents', 'skills', skillDirName);
+  ensureSymlink(packageDir, agentsTargetAbs);
+  materializations.push({
+    target: normalizeRelativePath(relative(repoRoot, agentsTargetAbs)),
+    mode: 'symlink',
+  });
+
+  return {
+    packageName: packageMetadata.packageName,
+    direct: directTargetMap.has(packageMetadata.packageName),
+    requestedTarget: directTargetMap.get(packageMetadata.packageName) || null,
+    packageVersion: packageMetadata.packageVersion,
+    sourcePackagePath: normalizeRelativePath(relative(repoRoot, packageDir)),
+    materializations,
+  };
+}
+
+export function rebuildInstallState(repoRoot, directTargetMap, {
+  listInstalledPackageDirs,
+  parseSkillFrontmatterFile,
+  readPackageMetadata,
+  normalizeRelativePath,
+} = {}) {
+  const packageDirs = listInstalledPackageDirs(join(repoRoot, 'node_modules'));
+  const installs = {};
+
+  for (const packageDir of packageDirs) {
+    const skillFile = join(packageDir, 'SKILL.md');
+    if (!existsSync(skillFile)) continue;
+
+    const record = buildInstallRecord(repoRoot, packageDir, directTargetMap, {
+      parseSkillFrontmatterFile,
+      readPackageMetadata,
+      normalizeRelativePath,
+    });
+    if (!record) continue;
+
+    installs[record.packageName] = {
+      direct: record.direct,
+      requested_target: record.requestedTarget,
+      package_version: record.packageVersion,
+      source_package_path: record.sourcePackagePath,
+      materializations: record.materializations,
+    };
+  }
+
+  const state = { version: 1, installs };
+  writeInstallState(repoRoot, state);
+  return state;
+}

package/src/infrastructure/runtime/open-browser.js

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+
+export function openBrowser(url) {
+  if (process.env.AGENTPACK_DISABLE_BROWSER === '1') return;
+
+  const command = process.platform === 'darwin'
+    ? 'open'
+    : process.platform === 'win32'
+      ? 'start'
+      : 'xdg-open';
+
+  try {
+    spawn(command, [url], {
+      detached: true,
+      stdio: 'ignore',
+    }).unref();
+  } catch {
+    // Browser launch failure should not fail the core dev workflow.
+  }
+}

package/src/infrastructure/runtime/skill-dev-workbench-server.js

@@ -0,0 +1,96 @@
+import http from 'node:http';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AgentpackError } from '../../utils/errors.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..', '..', '..');
+const htmlPath = join(projectRoot, 'src', 'dashboard', 'index.html');
+const bundlePath = process.env.AGENTPACK_DASHBOARD_BUNDLE_PATH
+  ? resolve(process.cwd(), process.env.AGENTPACK_DASHBOARD_BUNDLE_PATH)
+  : join(projectRoot, 'src', 'dashboard', 'dist', 'dashboard.js');
+
+function ensureDashboardBundle() {
+  if (existsSync(bundlePath)) return;
+
+  throw new AgentpackError('Skill workbench bundle is missing from this install', {
+    code: 'missing_skill_workbench_bundle',
+    suggestion: 'Reinstall agentpack or rebuild the dashboard bundle before starting skills dev.',
+    path: bundlePath,
+  });
+}
+
+export async function startSkillDevWorkbenchServer({ buildModel, defaultSkill, onAction = null }) {
+  ensureDashboardBundle();
+
+  const server = http.createServer(async (req, res) => {
+    if (!req.url) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+
+    const parsedUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+    if (parsedUrl.pathname === '/api/model') {
+      const skillParam = parsedUrl.searchParams.get('skill') || defaultSkill;
+      try {
+        const model = buildModel(skillParam);
+        if (!model) {
+          res.writeHead(404, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Skill not found' }));
+          return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(model));
+      } catch (error) {
+        res.writeHead(500, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: error.message }));
+      }
+      return;
+    }
+
+    if (req.method === 'POST' && parsedUrl.pathname.startsWith('/api/actions/')) {
+      const action = parsedUrl.pathname.slice('/api/actions/'.length);
+      res.writeHead(200, { 'content-type': 'application/json' });
+      try {
+        const result = onAction ? await onAction(action) : { refreshed: true };
+        res.end(JSON.stringify({ ok: true, action, result }));
+      } catch (error) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ ok: false, action, error: error.message }));
+      }
+      return;
+    }
+
+    if (parsedUrl.pathname === '/') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      res.end(readFileSync(htmlPath, 'utf-8'));
+      return;
+    }
+
+    if (parsedUrl.pathname === '/assets/dashboard.js') {
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' });
+      res.end(readFileSync(bundlePath, 'utf-8'));
+      return;
+    }
+
+    res.writeHead(404);
+    res.end();
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      resolve({
+        port: address.port,
+        url: `http://127.0.0.1:${address.port}`,
+        close() {
+          server.close();
+        },
+      });
+    });
+  });
+}

package/src/infrastructure/runtime/watch-skill-workbench.js

@@ -0,0 +1,68 @@
+import { watch } from 'node:fs';
+import { join } from 'node:path';
+import { parseSkillFrontmatterFile } from '../../domain/skills/skill-model.js';
+
+export function watchSkillWorkbench(repoRoot, skillDir, onRefresh) {
+  const staticWatchers = [];
+  const sourceWatchers = new Map();
+  let timer = null;
+
+  const refresh = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      onRefresh();
+    }, 50);
+  };
+
+  const watchPath = (pathValue) => {
+    try {
+      const watcher = watch(pathValue, refresh);
+      return watcher;
+    } catch {
+      // Ignore paths that cannot be watched for now.
+      return null;
+    }
+  };
+
+  const syncSourceWatchers = () => {
+    let metadata;
+    try {
+      metadata = parseSkillFrontmatterFile(skillFile);
+    } catch {
+      return;
+    }
+
+    const nextSources = new Set(metadata.sources.map((source) => join(repoRoot, source)));
+
+    for (const [pathValue, watcher] of sourceWatchers.entries()) {
+      if (nextSources.has(pathValue)) continue;
+      watcher.close();
+      sourceWatchers.delete(pathValue);
+    }
+
+    for (const pathValue of nextSources) {
+      if (sourceWatchers.has(pathValue)) continue;
+      const watcher = watchPath(pathValue);
+      if (watcher) sourceWatchers.set(pathValue, watcher);
+    }
+  };
+
+  const skillFile = join(skillDir, 'SKILL.md');
+  const packageJsonPath = join(skillDir, 'package.json');
+  const skillFileWatcher = watch(skillFile, () => {
+    syncSourceWatchers();
+    refresh();
+  });
+  staticWatchers.push(skillFileWatcher);
+  const packageWatcher = watchPath(packageJsonPath);
+  if (packageWatcher) staticWatchers.push(packageWatcher);
+  syncSourceWatchers();
+
+  return {
+    close() {
+      clearTimeout(timer);
+      for (const watcher of staticWatchers) watcher.close();
+      for (const watcher of sourceWatchers.values()) watcher.close();
+    },
+  };
+}

package/src/infrastructure/runtime/watch-tree.js

@@ -0,0 +1,44 @@
+import { existsSync, readdirSync, watch } from 'node:fs';
+import { join } from 'node:path';
+
+export function watchDirectoryTree(rootDir, onChange) {
+  const watchers = new Map();
+
+  const watchDir = (dirPath) => {
+    if (watchers.has(dirPath) || !existsSync(dirPath)) return;
+
+    let entries = [];
+    try {
+      entries = readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    const watcher = watch(dirPath, (_eventType, filename) => {
+      if (filename) {
+        const changedPath = join(dirPath, String(filename));
+        if (existsSync(changedPath)) {
+          watchDir(changedPath);
+        }
+      }
+
+      onChange();
+    });
+
+    watchers.set(dirPath, watcher);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      watchDir(join(dirPath, entry.name));
+    }
+  };
+
+  watchDir(rootDir);
+
+  return {
+    close() {
+      for (const watcher of watchers.values()) watcher.close();
+      watchers.clear();
+    },
+  };
+}

package/src/lib/plugins.js

@@ -1,11 +1,12 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, watch, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { resolveDependencyClosure } from '../domain/skills/skill-graph.js';
+import { normalizeRepoPath, parseSkillFrontmatterFile, readPackageMetadata } from '../domain/skills/skill-model.js';
+import { loadPluginDefinition } from '../domain/plugins/load-plugin-definition.js';
+import { watchDirectoryTree } from '../infrastructure/runtime/watch-tree.js';
 import {
   findPackageDirByName,
-  normalizeRepoPath,
-  parseSkillFrontmatterFile,
-  readPackageMetadata,
   syncSkillDependencies,
 } from './skills.js';
 import { findRepoRoot } from './context.js';
@@ -76,50 +77,30 @@ function collectPluginLocalSkillDirs(pluginDir) {
 }
 
 function resolveBundleClosure(repoRoot, pluginDir, directRequires) {
-  const seen = new Set();
-  const queue = [...directRequires];
-  const bundled = [];
-  const unresolved = [];
-
-  while (queue.length > 0) {
-    const packageName = queue.shift();
-    if (seen.has(packageName)) continue;
-    seen.add(packageName);
-
-    const resolvedPackage = resolvePackageDir(repoRoot, pluginDir, packageName);
-    if (!resolvedPackage) {
-      unresolved.push(packageName);
-      continue;
-    }
-
-    const skillFile = join(resolvedPackage.packageDir, 'SKILL.md');
-    if (!existsSync(skillFile)) {
-      unresolved.push(packageName);
-      continue;
-    }
-
-    const metadata = parseSkillFrontmatterFile(skillFile);
-    const packageMetadata = readPackageMetadata(resolvedPackage.packageDir);
-
-    bundled.push({
-      packageName,
-      packageVersion: packageMetadata.packageVersion,
-      skillName: metadata.name,
-      skillFile,
-      packageDir: resolvedPackage.packageDir,
-      source: resolvedPackage.source,
-      requires: metadata.requires,
-    });
-
-    for (const requirement of metadata.requires) {
-      if (!seen.has(requirement)) queue.push(requirement);
-    }
-  }
-
-  bundled.sort((a, b) => a.packageName.localeCompare(b.packageName));
-  unresolved.sort();
+  const { resolved, unresolved } = resolveDependencyClosure(directRequires, {
+    resolveNode(packageName) {
+      const resolvedPackage = resolvePackageDir(repoRoot, pluginDir, packageName);
+      if (!resolvedPackage) return null;
+
+      const skillFile = join(resolvedPackage.packageDir, 'SKILL.md');
+      if (!existsSync(skillFile)) return null;
+
+      const metadata = parseSkillFrontmatterFile(skillFile);
+      const packageMetadata = readPackageMetadata(resolvedPackage.packageDir);
+
+      return {
+        packageName,
+        packageVersion: packageMetadata.packageVersion,
+        skillName: metadata.name,
+        skillFile,
+        packageDir: resolvedPackage.packageDir,
+        source: resolvedPackage.source,
+        requires: metadata.requires,
+      };
+    },
+  });
 
-  return { bundled, unresolved };
+  return { bundled: resolved, unresolved };
 }
 
 function stagePluginRuntimeFiles(pluginDir, stageDir) {
@@ -130,48 +111,6 @@ function stagePluginRuntimeFiles(pluginDir, stageDir) {
   }
 }
 
-function watchDirectoryTree(rootDir, onChange) {
-  const watchers = new Map();
-
-  const watchDir = (dirPath) => {
-    if (watchers.has(dirPath) || !existsSync(dirPath)) return;
-
-    let entries = [];
-    try {
-      entries = readdirSync(dirPath, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
-    const watcher = watch(dirPath, (_eventType, filename) => {
-      if (filename) {
-        const changedPath = join(dirPath, String(filename));
-        if (existsSync(changedPath)) {
-          watchDir(changedPath);
-        }
-      }
-
-      onChange();
-    });
-
-    watchers.set(dirPath, watcher);
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      watchDir(join(dirPath, entry.name));
-    }
-  };
-
-  watchDir(rootDir);
-
-  return {
-    close() {
-      for (const watcher of watchers.values()) watcher.close();
-      watchers.clear();
-    },
-  };
-}
-
 export function buildPlugin(target, {
   cwd = process.cwd(),
   clean = false,
@@ -278,27 +217,16 @@ export function startPluginDev(target, {
 }
 
 export function inspectPluginBundle(target, { cwd = process.cwd() } = {}) {
-  const repoRoot = findRepoRoot(cwd);
-  const pluginDir = resolvePluginDir(repoRoot, target);
-  const pluginManifestPath = join(pluginDir, '.claude-plugin', 'plugin.json');
-  const pluginManifest = existsSync(pluginManifestPath)
-    ? JSON.parse(readFileSync(pluginManifestPath, 'utf-8'))
-    : null;
-
-  const packageMetadata = readPackageMetadata(pluginDir);
-  if (!packageMetadata.packageName || !packageMetadata.packageVersion) {
-    throw new ValidationError('plugin package.json missing name or version', {
-      code: 'missing_plugin_package_metadata',
-      suggestion: normalizeRepoPath(repoRoot, join(pluginDir, 'package.json')),
-    });
-  }
-
-  if (!pluginManifest) {
-    throw new ValidationError('plugin missing .claude-plugin/plugin.json', {
-      code: 'missing_plugin_manifest',
-      suggestion: normalizeRepoPath(repoRoot, join(pluginDir, '.claude-plugin', 'plugin.json')),
-    });
-  }
+  const definition = loadPluginDefinition(target, { cwd, requirementLevel: 'inspect' });
+  const {
+    repoRoot,
+    pluginDir,
+    packageJson,
+    packageName,
+    packageVersion,
+    pluginManifest,
+    pluginManifestPath,
+  } = definition;
 
   const localSkills = collectPluginLocalSkills(pluginDir);
   const directRequires = [...new Set(localSkills.flatMap((skill) => skill.requires))].sort();
@@ -306,9 +234,9 @@ export function inspectPluginBundle(target, { cwd = process.cwd() } = {}) {
   const directPackageSet = new Set(directRequires);
 
   return {
-    pluginName: pluginManifest.name || packageMetadata.packageName,
-    packageName: packageMetadata.packageName,
-    packageVersion: packageMetadata.packageVersion,
+    pluginName: pluginManifest.name || packageName,
+    packageName,
+    packageVersion,
     pluginPath: normalizeRepoPath(repoRoot, pluginDir),
     pluginManifestPath: normalizeRepoPath(repoRoot, pluginManifestPath),
     localSkills: localSkills.map((skill) => ({
@@ -341,10 +269,11 @@ export function inspectPluginBundle(target, { cwd = process.cwd() } = {}) {
 }
 
 export function validatePluginBundle(target, { cwd = process.cwd() } = {}) {
-  const repoRoot = findRepoRoot(cwd);
-  const pluginDir = resolvePluginDir(repoRoot, target);
+  const { repoRoot, pluginDir, packageJson } = loadPluginDefinition(target, {
+    cwd,
+    requirementLevel: 'validate',
+  });
   const result = inspectPluginBundle(target, { cwd });
-  const packageMetadata = readPackageMetadata(pluginDir);
   const issues = [];
   const localSkillNames = new Set(result.localSkills.map((skill) => skill.localName));
   const bundledSkillNames = new Map();
@@ -361,7 +290,7 @@ export function validatePluginBundle(target, { cwd = process.cwd() } = {}) {
 
   for (const localSkill of result.localSkills) {
     for (const packageName of localSkill.requires) {
-      const declared = packageMetadata.devDependencies[packageName];
+      const declared = packageJson.devDependencies?.[packageName];
       const resolvedPackage = resolvePackageDir(repoRoot, pluginDir, packageName);
       if (!declared || !resolvedPackage) {
         coveredPackages.add(packageName);