@alavida/agentpack 0.1.2 → 0.1.3

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

@@ -26,11 +26,13 @@ export function skillsCommand() {
     .command('dev')
     .description('Link one local packaged skill for local Claude and agent discovery')
     .option('--no-sync', 'Skip syncing managed package dependencies from requires')
+    .option('--no-dashboard', 'Skip starting the local skill development workbench')
     .argument('<target>', 'Packaged skill directory or SKILL.md path')
-    .action((target, opts, command) => {
+    .action(async (target, opts, command) => {
       const globalOpts = command.optsWithGlobals();
       const session = startSkillDev(target, {
         sync: opts.sync,
+        dashboard: opts.dashboard,
         onStart(result) {
           if (globalOpts.json) {
             output.json(result);
@@ -45,6 +47,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:');
@@ -72,6 +77,7 @@ export function skillsCommand() {
 
       process.once('SIGTERM', stop);
       process.once('SIGINT', stop);
+      await session.ready;
     });
 
   cmd

package/src/dashboard/App.jsx

@@ -0,0 +1,343 @@
+import { useEffect, useLayoutEffect, useState, useCallback, useRef } from 'react';
+import { fetchWorkbenchModel, runWorkbenchAction } from './lib/api.js';
+import { getSkillFromHash, setSkillHash, onHashChange } from './lib/router.js';
+import { SkillGraph } from './components/SkillGraph.jsx';
+import { InspectorPanel } from './components/InspectorPanel.jsx';
+import { Breadcrumbs } from './components/Breadcrumbs.jsx';
+import { ControlStrip } from './components/ControlStrip.jsx';
+import { Tooltip } from './components/Tooltip.jsx';
+
+export function App() {
+  const [model, setModel] = useState(null);
+  const [selectedId, setSelectedId] = useState(null);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [busyAction, setBusyAction] = useState(null);
+  const [labelsVisible, setLabelsVisible] = useState(true);
+  const [knowledgeVisible, setKnowledgeVisible] = useState(true);
+  const [resetZoomSignal, setResetZoomSignal] = useState(0);
+  const [lightMode, setLightMode] = useState(false);
+  const [trail, setTrail] = useState([]);
+  const [tooltipNode, setTooltipNode] = useState(null);
+  const [tooltipPos, setTooltipPos] = useState(null);
+  const inspectedNode = model?.nodes.find((n) => n.id === selectedId) || null;
+
+  useLayoutEffect(() => {
+    document.documentElement.setAttribute('data-theme', lightMode ? 'light' : 'dark');
+  }, [lightMode]);
+
+  const loadModel = useCallback(async (skillPackageName) => {
+    try {
+      setLoading(true);
+      setError(null);
+      const nextModel = await fetchWorkbenchModel(skillPackageName);
+      setModel(nextModel);
+      setSelectedId(null);
+      return nextModel;
+    } catch (err) {
+      setError(err.message);
+      return null;
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  // Initial load
+  useEffect(() => {
+    const hashSkill = getSkillFromHash();
+    loadModel(hashSkill).then((m) => {
+      if (m) {
+        const entry = { packageName: m.selected.id, name: m.selected.name };
+        if (hashSkill) {
+          setTrail([entry]);
+        } else {
+          setTrail([entry]);
+          setSkillHash(m.selected.id);
+        }
+      }
+    });
+  }, [loadModel]);
+
+  // Hash change listener
+  useEffect(() => {
+    onHashChange((skillPackageName) => {
+      if (skillPackageName) {
+        loadModel(skillPackageName).then((m) => {
+          if (m) {
+            setTrail((prev) => {
+              const existingIndex = prev.findIndex((e) => e.packageName === skillPackageName);
+              if (existingIndex >= 0) {
+                return prev.slice(0, existingIndex + 1);
+              }
+              return [...prev, { packageName: m.selected.id, name: m.selected.name }];
+            });
+          }
+        });
+      }
+    });
+  }, [loadModel]);
+
+  function navigateToSkill(packageName) {
+    setSkillHash(packageName);
+  }
+
+  function handleBreadcrumbNavigate(packageName, index) {
+    setTrail((prev) => prev.slice(0, index + 1));
+    setSkillHash(packageName);
+  }
+
+  async function handleAction(action) {
+    if (action === 'reset-zoom') {
+      setResetZoomSignal((s) => s + 1);
+      return;
+    }
+
+    if (action === 'refresh') {
+      const hashSkill = getSkillFromHash();
+      setBusyAction('refresh');
+      await loadModel(hashSkill);
+      setBusyAction(null);
+      return;
+    }
+
+    try {
+      setBusyAction(action);
+      await runWorkbenchAction(action);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setBusyAction(null);
+    }
+  }
+
+  const handleHover = useCallback((node, pos) => {
+    setTooltipNode(node);
+    setTooltipPos(pos);
+  }, []);
+
+  const handleHoverEnd = useCallback(() => {
+    setTooltipNode(null);
+    setTooltipPos(null);
+  }, []);
+
+  const handleGraphClick = useCallback((nodeId) => {
+    setSelectedId((prev) => prev === nodeId ? null : nodeId);
+  }, []);
+
+  return (
+    <>
+      {/* Header */}
+      <header style={{
+        padding: '20px 40px 0',
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'flex-start',
+        flexShrink: 0,
+      }}>
+        <div>
+          <div style={{
+            fontFamily: 'var(--font-mono)',
+            fontVariant: 'small-caps',
+            textTransform: 'uppercase',
+            letterSpacing: 3,
+            fontSize: 9,
+            color: 'var(--text-dim)',
+            marginBottom: 4,
+          }}>
+            Agentpack
+          </div>
+          <div style={{
+            fontFamily: 'var(--font-body)',
+            fontSize: 28,
+            fontWeight: 400,
+            fontStyle: 'italic',
+            color: 'var(--text)',
+          }}>
+            Skill Graph
+          </div>
+          <hr style={{
+            width: 36,
+            height: 1,
+            background: 'var(--status-current)',
+            border: 'none',
+            marginTop: 10,
+          }} />
+        </div>
+        <div style={{
+          display: 'flex',
+          gap: 20,
+          alignItems: 'center',
+        }}>
+          <LegendItem color="var(--edge-provenance)" label="Source" shape="diamond" />
+          <LegendItem color="#c45454" label="Changed" shape="diamond" />
+          <LegendItem color="var(--status-current)" label="Current" shape="dot" />
+          <LegendItem color="var(--status-stale)" label="Stale" shape="dot" />
+          <LegendItem color="var(--status-affected)" label="Affected" shape="ring" />
+          <LegendItem color="var(--edge-requires)" label="Requires" shape="line" />
+          <LegendItem color="var(--edge-provenance)" label="Provenance" shape="dashed" />
+        </div>
+      </header>
+
+      {/* Breadcrumbs */}
+      <Breadcrumbs trail={trail} onNavigate={handleBreadcrumbNavigate} />
+
+      {/* Main area */}
+      <div style={{ flex: 1, position: 'relative', minHeight: 0 }}>
+        {loading && !model && (
+          <div style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '100%',
+            fontFamily: 'var(--font-mono)',
+            fontSize: 12,
+            color: 'var(--text-dim)',
+          }}>
+            Loading...
+          </div>
+        )}
+
+        {error && (
+          <div style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '100%',
+            gap: 16,
+          }}>
+            <div style={{
+              fontFamily: 'var(--font-body)',
+              fontSize: 18,
+              fontStyle: 'italic',
+              color: 'var(--status-stale)',
+            }}>
+              {error}
+            </div>
+            <button
+              type="button"
+              onClick={() => handleAction('refresh')}
+              style={{
+                fontFamily: 'var(--font-mono)',
+                fontSize: 11,
+                background: 'var(--surface)',
+                border: '1px solid var(--border-bright)',
+                color: 'var(--text-dim)',
+                padding: '8px 16px',
+                cursor: 'pointer',
+                letterSpacing: '0.04em',
+              }}
+            >
+              Retry
+            </button>
+          </div>
+        )}
+
+        {model && !error && (
+          <SkillGraph
+            model={model}
+            selectedId={selectedId}
+            onSelect={handleGraphClick}
+            onHover={handleHover}
+            onHoverEnd={handleHoverEnd}
+            labelsVisible={labelsVisible}
+            knowledgeVisible={knowledgeVisible}
+            resetZoomSignal={resetZoomSignal}
+          />
+        )}
+
+        {model && model.nodes.length === 1 && model.nodes[0].type === 'skill' && (
+          <div style={{
+            position: 'absolute',
+            bottom: 80,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            fontFamily: 'var(--font-body)',
+            fontSize: 14,
+            fontStyle: 'italic',
+            color: 'var(--text-faint)',
+          }}>
+            No dependencies or sources found.
+          </div>
+        )}
+      </div>
+
+      {/* Tooltip */}
+      <Tooltip node={tooltipNode} position={tooltipPos} />
+
+      {/* Inspector Panel */}
+      <InspectorPanel
+        node={inspectedNode}
+        onClose={() => setSelectedId(null)}
+        onNavigate={navigateToSkill}
+      />
+
+      {/* Control Strip */}
+      <ControlStrip
+        onAction={handleAction}
+        busyAction={busyAction}
+        labelsVisible={labelsVisible}
+        onToggleLabels={() => setLabelsVisible((v) => !v)}
+        knowledgeVisible={knowledgeVisible}
+        onToggleKnowledge={() => setKnowledgeVisible((v) => !v)}
+        lightMode={lightMode}
+        onToggleTheme={() => setLightMode((v) => !v)}
+      />
+    </>
+  );
+}
+
+function LegendItem({ color, label, shape }) {
+  return (
+    <div style={{
+      display: 'flex',
+      alignItems: 'center',
+      gap: 6,
+      fontFamily: 'var(--font-mono)',
+      fontSize: 10,
+      color: 'var(--text-dim)',
+      letterSpacing: '0.04em',
+    }}>
+      {shape === 'dot' && (
+        <div style={{
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          background: color,
+        }} />
+      )}
+      {shape === 'ring' && (
+        <div style={{
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          background: 'transparent',
+          border: `1.5px solid ${color}`,
+        }} />
+      )}
+      {shape === 'diamond' && (
+        <svg width="12" height="12" viewBox="-6 -6 12 12" style={{ display: 'block' }}>
+          <path d="M0,-5 L5,0 L0,5 L-5,0 Z" fill={color} opacity={0.6} />
+        </svg>
+      )}
+      {shape === 'line' && (
+        <div style={{
+          width: 20,
+          height: 2,
+          borderRadius: 1,
+          background: color,
+          opacity: 0.6,
+        }} />
+      )}
+      {shape === 'dashed' && (
+        <div style={{
+          width: 20,
+          height: 0,
+          borderTop: `2px dashed ${color}`,
+          opacity: 0.5,
+        }} />
+      )}
+      {label}
+    </div>
+  );
+}

package/src/dashboard/components/Breadcrumbs.jsx

@@ -0,0 +1,45 @@
+export function Breadcrumbs({ trail, onNavigate }) {
+  if (!trail || trail.length === 0) return null;
+
+  return (
+    <nav style={{
+      display: 'flex',
+      alignItems: 'center',
+      gap: 6,
+      fontFamily: 'var(--font-mono)',
+      fontSize: 11,
+      letterSpacing: '0.02em',
+      color: 'var(--text-dim)',
+      padding: '0 40px',
+      height: 32,
+      borderBottom: '1px solid var(--border)',
+      flexShrink: 0,
+    }}>
+      {trail.map((entry, index) => {
+        const isLast = index === trail.length - 1;
+        return (
+          <span key={entry.packageName} style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+            {index > 0 && <span style={{ color: 'var(--text-faint)' }}>›</span>}
+            {isLast ? (
+              <span style={{ color: 'var(--text)' }}>
+                {entry.name || entry.packageName}
+              </span>
+            ) : (
+              <span
+                onClick={() => onNavigate(entry.packageName, index)}
+                style={{
+                  cursor: 'pointer',
+                  transition: 'color 200ms ease',
+                }}
+                onMouseEnter={(e) => { e.target.style.color = 'var(--text)'; }}
+                onMouseLeave={(e) => { e.target.style.color = 'var(--text-dim)'; }}
+              >
+                {entry.name || entry.packageName}
+              </span>
+            )}
+          </span>
+        );
+      })}
+    </nav>
+  );
+}