@alavida/agentpack 0.1.2 → 0.1.4

package/src/application/skills/build-skill-workbench-model.js

@@ -0,0 +1,194 @@
+function explainNodeStatus(status) {
+  if (status === 'affected') return 'Affected by upstream authored state changes';
+  if (status === 'changed') return 'Changed since recorded build-state';
+  if (status === 'stale') return 'Stale against recorded build-state';
+  return 'No current lifecycle issue detected';
+}
+
+export function buildSkillWorkbenchModel({
+  repoRoot,
+  selectedSkill,
+  dependencyRecords = [],
+  sourceStatuses = new Map(),
+  selectedStatus = 'unknown',
+}) {
+  const selectedNode = {
+    id: selectedSkill.packageName,
+    type: 'skill',
+    repoRoot,
+    packageName: selectedSkill.packageName,
+    name: selectedSkill.name,
+    skillFile: selectedSkill.skillFile,
+    status: selectedStatus,
+    explanation: selectedStatus === 'stale'
+      ? `Stale because one or more recorded sources changed: ${selectedSkill.sources.join(', ')}`
+      : 'Current against recorded build-state',
+  };
+
+  const sourceNodes = selectedSkill.sources.map((source) => ({
+    id: `source:${source}`,
+    type: 'source',
+    path: source,
+    status: sourceStatuses.get(source) || 'unknown',
+    explanation: explainNodeStatus(sourceStatuses.get(source) || 'unknown'),
+  }));
+
+  const dependencyNodes = dependencyRecords.map((dependency) => ({
+    id: dependency.packageName,
+    type: 'dependency',
+    packageName: dependency.packageName,
+    status: dependency.status || 'unknown',
+    explanation: explainNodeStatus(dependency.status || 'unknown'),
+  }));
+
+  return {
+    selected: selectedNode,
+    nodes: [selectedNode, ...sourceNodes, ...dependencyNodes],
+    edges: [
+      ...sourceNodes.map((node) => ({
+        source: node.id,
+        target: selectedNode.id,
+        kind: 'provenance',
+      })),
+      ...dependencyNodes.map((node) => ({
+        source: selectedNode.id,
+        target: node.id,
+        kind: 'requires',
+      })),
+    ],
+  };
+}
+
+export function buildTransitiveSkillWorkbenchModel({
+  repoRoot,
+  targetPackageName,
+  skillGraph,
+  statusMap,
+  changedSources = new Set(),
+  resolveSkillSources,
+  resolveSkillRequires,
+}) {
+  const targetGraphNode = skillGraph.get(targetPackageName);
+  if (!targetGraphNode) return null;
+
+  const depthMap = new Map();
+  const parentMap = new Map();
+  const bfsOrder = [];
+  const queue = [{ name: targetPackageName, depth: 0, parent: null }];
+
+  while (queue.length > 0) {
+    const { name, depth, parent } = queue.shift();
+    if (depthMap.has(name)) continue;
+
+    depthMap.set(name, depth);
+    if (parent !== null) parentMap.set(name, parent);
+    bfsOrder.push(name);
+
+    const graphNode = skillGraph.get(name);
+
+    // Use graph dependencies if available, fall back to declared requires
+    const deps = graphNode
+      ? graphNode.dependencies
+      : [];
+
+    // Also include declared requires that aren't in graph dependencies
+    const declared = resolveSkillRequires ? resolveSkillRequires(name) : [];
+    const allDeps = [...new Set([...deps, ...declared])];
+
+    for (const dep of allDeps) {
+      if (!depthMap.has(dep)) {
+        queue.push({ name: dep, depth: depth + 1, parent: name });
+      }
+    }
+  }
+
+  const nodes = [];
+  const edges = [];
+  const sourceTracker = new Map();
+
+  for (const packageName of bfsOrder) {
+    const graphNode = skillGraph.get(packageName);
+    if (!graphNode) {
+      nodes.push({
+        id: packageName,
+        type: 'dependency',
+        packageName,
+        name: packageName.split('/').pop(),
+        description: null,
+        version: null,
+        status: 'unknown',
+        explanation: 'Package not found in skill graph',
+        depth: depthMap.get(packageName),
+      });
+      continue;
+    }
+
+    const isTarget = packageName === targetPackageName;
+    const status = statusMap?.get(packageName) || 'unknown';
+
+    nodes.push({
+      id: packageName,
+      type: isTarget ? 'skill' : 'dependency',
+      packageName,
+      name: graphNode.name,
+      description: graphNode.description || null,
+      version: graphNode.packageVersion || null,
+      status,
+      explanation: explainNodeStatus(status),
+      depth: depthMap.get(packageName),
+    });
+
+    const sources = resolveSkillSources(packageName);
+    for (const sourcePath of sources) {
+      const sourceId = `source:${sourcePath}`;
+      if (!sourceTracker.has(sourceId)) {
+        sourceTracker.set(sourceId, { path: sourcePath, usedBy: [] });
+      }
+      sourceTracker.get(sourceId).usedBy.push(packageName);
+    }
+
+    const deps = graphNode ? graphNode.dependencies : [];
+    const declared = resolveSkillRequires ? resolveSkillRequires(packageName) : [];
+    const allDeps = [...new Set([...deps, ...declared])];
+
+    for (const dep of allDeps) {
+      if (depthMap.has(dep)) {
+        edges.push({
+          source: packageName,
+          target: dep,
+          kind: 'requires',
+        });
+      }
+    }
+  }
+
+  const sourceNodes = [];
+  for (const [sourceId, sourceData] of sourceTracker) {
+    const isChanged = changedSources.has(sourceData.path);
+    sourceNodes.push({
+      id: sourceId,
+      type: 'source',
+      path: sourceData.path,
+      status: isChanged ? 'changed' : 'current',
+      explanation: isChanged ? 'Changed since recorded build-state' : 'No current lifecycle issue detected',
+      depth: 0,
+      usedBy: sourceData.usedBy,
+    });
+
+    for (const skillPackageName of sourceData.usedBy) {
+      edges.push({
+        source: sourceId,
+        target: skillPackageName,
+        kind: 'provenance',
+      });
+    }
+  }
+
+  const selectedNode = nodes.find((n) => n.id === targetPackageName);
+
+  return {
+    selected: selectedNode,
+    nodes: [...sourceNodes, ...nodes],
+    edges,
+  };
+}

package/src/application/skills/run-skill-workbench-action.js

@@ -0,0 +1,23 @@
+import { inspectSkillDependencies } from '../../lib/skills.js';
+import { inspectStaleSkillUseCase } from './list-stale-skills.js';
+import { validateSkillsUseCase } from './validate-skills.js';
+
+export function runSkillWorkbenchAction(action, context) {
+  if (action === 'check-stale') {
+    return inspectStaleSkillUseCase(context.packageName, { cwd: context.cwd });
+  }
+
+  if (action === 'show-dependencies') {
+    return inspectSkillDependencies(context.packageName, { cwd: context.cwd });
+  }
+
+  if (action === 'validate-skill') {
+    return validateSkillsUseCase(context.target, { cwd: context.cwd });
+  }
+
+  if (action === 'refresh') {
+    return { refreshed: true };
+  }
+
+  throw new Error(`Unsupported workbench action: ${action}`);
+}

package/src/application/skills/start-skill-dev-workbench.js

@@ -0,0 +1,192 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseSkillFrontmatterFile, readPackageMetadata, normalizeDisplayPath } from '../../domain/skills/skill-model.js';
+import { readBuildState, compareRecordedSources } from '../../domain/skills/skill-provenance.js';
+import { buildSkillGraph, buildSkillStatusMap } from '../../domain/skills/skill-graph.js';
+import { buildTransitiveSkillWorkbenchModel } from './build-skill-workbench-model.js';
+import { startSkillDevWorkbenchServer } from '../../infrastructure/runtime/skill-dev-workbench-server.js';
+import { openBrowser } from '../../infrastructure/runtime/open-browser.js';
+import { watchSkillWorkbench } from '../../infrastructure/runtime/watch-skill-workbench.js';
+import { runSkillWorkbenchAction } from './run-skill-workbench-action.js';
+
+function listPackagedSkillDirs(repoRoot) {
+  const stack = [repoRoot];
+  const results = [];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    let hasSkillFile = false;
+    let hasPackageFile = false;
+
+    for (const entry of entries) {
+      if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.agentpack') continue;
+      const fullPath = join(current, entry.name);
+
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (entry.name === 'SKILL.md') hasSkillFile = true;
+      if (entry.name === 'package.json') hasPackageFile = true;
+    }
+
+    if (hasSkillFile && hasPackageFile) {
+      results.push(current);
+    }
+  }
+
+  return results.sort();
+}
+
+function findPackageDirByName(repoRoot, packageName) {
+  const stack = [repoRoot];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === '.git' || entry.name === 'node_modules') continue;
+      const fullPath = join(current, entry.name);
+
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (entry.name !== 'package.json') continue;
+
+      try {
+        const pkg = JSON.parse(readFileSync(fullPath, 'utf-8'));
+        if (pkg.name === packageName) return dirname(fullPath);
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  const nodeModulesPath = join(repoRoot, 'node_modules', ...packageName.split('/'));
+  if (existsSync(join(nodeModulesPath, 'SKILL.md'))) return nodeModulesPath;
+
+  return null;
+}
+
+function buildModelForSkill(repoRoot, targetPackageName) {
+  const packageDirs = listPackagedSkillDirs(repoRoot);
+  const skillGraph = buildSkillGraph(repoRoot, packageDirs, {
+    parseSkillFrontmatterFile,
+    readPackageMetadata,
+    findPackageDirByName: (root, name) => findPackageDirByName(root, name),
+    normalizeDisplayPath,
+  });
+
+  const buildState = readBuildState(repoRoot);
+  const staleSkills = new Set();
+  const changedSources = new Set(); // track individual changed source paths
+
+  for (const [packageName, record] of Object.entries(buildState.skills || buildState)) {
+    if (typeof record !== 'object' || !record.sources) continue;
+    try {
+      const changes = compareRecordedSources(repoRoot, record);
+      if (changes.length > 0) {
+        staleSkills.add(packageName);
+        for (const change of changes) changedSources.add(change.path);
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  const statusMap = buildSkillStatusMap(skillGraph, staleSkills);
+
+  function resolveSkillSources(packageName) {
+    const graphNode = skillGraph.get(packageName);
+    if (!graphNode) return [];
+
+    const skillFilePath = join(repoRoot, graphNode.skillFile);
+    try {
+      const metadata = parseSkillFrontmatterFile(skillFilePath);
+      return metadata.sources || [];
+    } catch {
+      return [];
+    }
+  }
+
+  function resolveSkillRequires(packageName) {
+    const graphNode = skillGraph.get(packageName);
+    if (!graphNode) return [];
+
+    const skillFilePath = join(repoRoot, graphNode.skillFile);
+    try {
+      const metadata = parseSkillFrontmatterFile(skillFilePath);
+      return metadata.requires || [];
+    } catch {
+      return [];
+    }
+  }
+
+  return buildTransitiveSkillWorkbenchModel({
+    repoRoot,
+    targetPackageName,
+    skillGraph,
+    statusMap,
+    changedSources,
+    resolveSkillSources,
+    resolveSkillRequires,
+  });
+}
+
+export async function startSkillDevWorkbench({
+  repoRoot,
+  skillDir,
+  open = true,
+  disableBrowser = false,
+}) {
+  const packageMetadata = readPackageMetadata(skillDir);
+  const defaultSkill = packageMetadata.packageName;
+
+  const server = await startSkillDevWorkbenchServer({
+    buildModel: (skillPackageName) => buildModelForSkill(repoRoot, skillPackageName),
+    defaultSkill,
+    onAction(action) {
+      return runSkillWorkbenchAction(action, {
+        cwd: repoRoot,
+        target: skillDir,
+        packageName: defaultSkill,
+      });
+    },
+  });
+
+  const watcher = watchSkillWorkbench(repoRoot, skillDir, () => {
+    // Model is rebuilt on each request, so no cache to invalidate
+  });
+
+  if (open && !disableBrowser) {
+    openBrowser(server.url);
+  }
+
+  return {
+    url: server.url,
+    port: server.port,
+    refresh() {
+      // no-op: models are built on demand per request
+    },
+    close() {
+      watcher.close();
+      server.close();
+    },
+  };
+}

package/src/cli.js

@@ -68,7 +68,7 @@ export function run(argv) {
     if (err instanceof AgentpackError) {
       const opts = program.opts?.() || {};
       if (opts.json) {
-        output.json({ error: err.code, message: err.message });
+        output.json(err.toJSON());
       } else {
         output.error(formatError(err));
       }

package/src/commands/skills.js

@@ -11,6 +11,7 @@ import {
   installSkills,
   listOutdatedSkills,
   resolveInstallTargets,
+  cleanupSkillDevSession,
   startSkillDev,
   unlinkSkill,
   uninstallSkills,
@@ -22,15 +23,20 @@ export function skillsCommand() {
   const cmd = new Command('skills')
     .description('Inspect and manage package-backed skills');
 
-  cmd
+  const devCmd = cmd
     .command('dev')
     .description('Link one local packaged skill for local Claude and agent discovery')
     .option('--no-sync', 'Skip syncing managed package dependencies from requires')
-    .argument('<target>', 'Packaged skill directory or SKILL.md path')
-    .action((target, opts, command) => {
+    .option('--no-dashboard', 'Skip starting the local skill development workbench')
+    .argument('[target]', 'Packaged skill directory or SKILL.md path')
+    .action(async (target, opts, command) => {
+      if (!target) {
+        command.help({ error: true });
+      }
       const globalOpts = command.optsWithGlobals();
       const session = startSkillDev(target, {
         sync: opts.sync,
+        dashboard: opts.dashboard,
         onStart(result) {
           if (globalOpts.json) {
             output.json(result);
@@ -45,6 +51,9 @@ export function skillsCommand() {
           for (const link of result.links) {
             output.write(`Linked: ${link}`);
           }
+          if (result.workbench?.enabled) {
+            output.write(`Workbench URL: ${result.workbench.url}`);
+          }
           output.write('Note: if your current agent session was already running, start a fresh session to pick up newly linked skills.');
           if (result.unresolved.length > 0) {
             output.write('Unresolved Dependencies:');
@@ -65,22 +74,37 @@ export function skillsCommand() {
         },
       });
 
-      const stop = () => {
-        session.close();
-        process.exit(0);
-      };
+      await session.ready;
+    });
+
+  devCmd
+    .command('cleanup')
+    .description('Remove recorded skills dev links for a stale session')
+    .option('--force', 'Remove recorded links even if the session pid still appears alive')
+    .action((opts, command) => {
+      const globalOpts = command.optsWithGlobals();
+      const result = cleanupSkillDevSession({ force: opts.force });
+
+      if (globalOpts.json) {
+        output.json(result);
+        return;
+      }
 
-      process.once('SIGTERM', stop);
-      process.once('SIGINT', stop);
+      output.write(`Cleaned: ${result.cleaned}`);
+      if (result.name) output.write(`Root Skill: ${result.name}`);
+      for (const removed of result.removed) {
+        output.write(`Removed: ${removed}`);
+      }
     });
 
   cmd
     .command('unlink')
     .description('Remove one locally linked skill from Claude and agent discovery paths')
+    .option('--recursive', 'Remove the active dev root and its recorded transitive links')
     .argument('<name>', 'Skill frontmatter name')
     .action((name, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = unlinkSkill(name);
+      const result = unlinkSkill(name, { recursive: opts.recursive });
 
       if (globalOpts.json) {
         output.json(result);