@alavida/agentpack 0.1.2 → 0.1.4

package/src/lib/skills.js

@@ -9,11 +9,13 @@ import {
   readNodeStatus,
 } from '../domain/skills/skill-graph.js';
 import { readInstallState } from '../infrastructure/fs/install-state-repository.js';
+import { readDevSession, writeDevSession, removeDevSession } from '../infrastructure/fs/dev-session-repository.js';
 import {
   ensureSkillLink,
   rebuildInstallState,
   removePathIfExists,
   removeSkillLinks,
+  removeSkillLinksByPaths,
   removeSkillLinksByNames,
 } from '../infrastructure/runtime/materialize-skills.js';
 import {
@@ -29,6 +31,7 @@ import {
   readBuildState,
   writeBuildState,
 } from '../domain/skills/skill-provenance.js';
+import { startSkillDevWorkbench } from '../application/skills/start-skill-dev-workbench.js';
 import { AgentpackError, EXIT_CODES, NetworkError, NotFoundError, ValidationError } from '../utils/errors.js';
 
 const GITHUB_PACKAGES_REGISTRY = 'https://npm.pkg.github.com';
@@ -170,6 +173,100 @@ function readPackageJson(packageDir) {
   };
 }
 
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === 'EPERM') return true;
+    if (error.code === 'ESRCH') return false;
+    return false;
+  }
+}
+
+function buildDevSessionNextSteps(command) {
+  return [{
+    action: 'run_command',
+    command,
+    reason: 'Use the dev session cleanup flow to remove recorded linked skills for this repo',
+  }];
+}
+
+function toDevSessionRecord(repoRoot, target, result, existing = null) {
+  const now = new Date().toISOString();
+  const rootSkill = result.linkedSkills.find((entry) => entry.name === result.name) || result.linkedSkills[0] || null;
+  return {
+    version: 1,
+    session_id: existing?.session_id || `dev-${now.replaceAll(':', '-').replaceAll('.', '-')}`,
+    status: 'active',
+    pid: process.pid,
+    repo_root: repoRoot,
+    target,
+    root_skill: rootSkill
+      ? {
+        name: rootSkill.name,
+        package_name: rootSkill.packageName,
+        path: rootSkill.path,
+      }
+      : null,
+    linked_skills: result.linkedSkills.map((entry) => ({
+      name: entry.name,
+      package_name: entry.packageName,
+      path: entry.path,
+    })),
+    links: result.links,
+    started_at: existing?.started_at || now,
+    updated_at: now,
+  };
+}
+
+function cleanupRecordedDevSession(repoRoot, session, status = 'stale') {
+  if (!session) {
+    return {
+      cleaned: false,
+      removed: [],
+      session: null,
+    };
+  }
+
+  writeDevSession(repoRoot, {
+    ...session,
+    status,
+    updated_at: new Date().toISOString(),
+  });
+  const removed = removeSkillLinksByPaths(repoRoot, session.links || [], normalizeDisplayPath);
+  removeDevSession(repoRoot);
+  return {
+    cleaned: removed.length > 0 || Boolean(session),
+    removed,
+    session,
+  };
+}
+
+function reconcileDevSession(repoRoot) {
+  const session = readDevSession(repoRoot);
+  if (!session) return null;
+
+  if (session.status === 'active' && isProcessAlive(session.pid)) {
+    throw new AgentpackError('A skills dev session is already active in this repo', {
+      code: 'skills_dev_session_active',
+      exitCode: EXIT_CODES.GENERAL,
+      nextSteps: [
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup'),
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup --force'),
+      ],
+      details: {
+        rootSkill: session.root_skill?.name || null,
+        pid: session.pid,
+        startedAt: session.started_at || null,
+      },
+    });
+  }
+
+  return cleanupRecordedDevSession(repoRoot, session, 'stale');
+}
+
 export function syncSkillDependencies(skillDir) {
   const skillFile = join(skillDir, 'SKILL.md');
   const metadata = parseSkillFrontmatterFile(skillFile);
@@ -263,25 +360,42 @@ export function devSkill(target, {
 export function startSkillDev(target, {
   cwd = process.cwd(),
   sync = true,
+  dashboard = true,
   onStart = () => {},
   onRebuild = () => {},
 } = {}) {
-  const repoRoot = findRepoRoot(cwd);
-  const { skillDir } = resolveLocalPackagedSkillDir(repoRoot, target);
+  const outerRepoRoot = findRepoRoot(cwd);
+  const { skillDir } = resolveLocalPackagedSkillDir(outerRepoRoot, target);
+  const repoRoot = findRepoRoot(skillDir);
+  reconcileDevSession(repoRoot);
   let closed = false;
   let timer = null;
   let currentNames = [];
   let watcher = null;
+  let workbench = null;
+  let initialResult = null;
+  let sessionRecord = null;
 
   const cleanup = () => {
     if (closed) return { name: currentNames[0] || null, unlinked: false, removed: [] };
     closed = true;
     clearTimeout(timer);
     if (watcher) watcher.close();
-    const removed = removeSkillLinksByNames(repoRoot, currentNames, normalizeDisplayPath);
+    if (workbench) workbench.close();
+    if (sessionRecord) {
+      writeDevSession(repoRoot, {
+        ...sessionRecord,
+        status: 'cleaning',
+        updated_at: new Date().toISOString(),
+      });
+    }
+    const removed = sessionRecord
+      ? removeSkillLinksByPaths(repoRoot, sessionRecord.links || [], normalizeDisplayPath)
+      : removeSkillLinksByNames(repoRoot, currentNames, normalizeDisplayPath);
+    removeDevSession(repoRoot);
     detachProcessCleanup();
     return {
-      name: currentNames[0] || null,
+      name: sessionRecord?.root_skill?.name || currentNames[0] || null,
       unlinked: removed.length > 0,
       removed,
     };
@@ -289,9 +403,14 @@ export function startSkillDev(target, {
 
   const processCleanupHandlers = new Map();
   const attachProcessCleanup = () => {
-    for (const eventName of ['exit', 'beforeExit', 'SIGINT', 'SIGTERM', 'SIGHUP']) {
+    const exitHandler = () => cleanup();
+    processCleanupHandlers.set('exit', exitHandler);
+    process.once('exit', exitHandler);
+
+    for (const eventName of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
       const handler = () => {
         cleanup();
+        process.exit(0);
       };
       processCleanupHandlers.set(eventName, handler);
       process.once(eventName, handler);
@@ -305,19 +424,58 @@ export function startSkillDev(target, {
     processCleanupHandlers.clear();
   };
 
-  const run = () => {
-    const result = devSkill(target, { cwd, sync });
+  const enrichResult = (result) => ({
+    ...result,
+    workbench: workbench
+      ? {
+        enabled: true,
+        url: workbench.url,
+        port: workbench.port,
+      }
+      : {
+        enabled: false,
+        url: null,
+        port: null,
+      },
+  });
+
+  const applyDevResult = (result) => {
     const nextNames = result.linkedSkills.map((entry) => entry.name);
     const staleNames = currentNames.filter((name) => !nextNames.includes(name));
     if (staleNames.length > 0) {
       removeSkillLinksByNames(repoRoot, staleNames, normalizeDisplayPath);
     }
     currentNames = nextNames;
+    sessionRecord = toDevSessionRecord(repoRoot, target, result, sessionRecord);
+    writeDevSession(repoRoot, sessionRecord);
     return result;
   };
 
-  const initialResult = run();
-  onStart(initialResult);
+  const startOrRefreshWorkbench = async () => {
+    if (dashboard && !workbench) {
+      workbench = await startSkillDevWorkbench({
+        repoRoot,
+        skillDir,
+        open: true,
+        disableBrowser: process.env.AGENTPACK_DISABLE_BROWSER === '1',
+      });
+    } else if (workbench) {
+      workbench.refresh();
+    }
+  };
+
+  initialResult = enrichResult(applyDevResult(devSkill(target, { cwd, sync })));
+  const ready = Promise.resolve(startOrRefreshWorkbench())
+    .then(() => {
+      const result = enrichResult(initialResult);
+      initialResult = result;
+      onStart(result);
+      return result;
+    })
+    .catch((error) => {
+      cleanup();
+      throw error;
+    });
 
   attachProcessCleanup();
 
@@ -325,25 +483,59 @@ export function startSkillDev(target, {
     if (closed) return;
     clearTimeout(timer);
     timer = setTimeout(() => {
-      try {
-        const result = run();
-        onRebuild(result);
-      } catch (error) {
-        onRebuild({ error });
-      }
+      Promise.resolve()
+        .then(() => applyDevResult(devSkill(target, { cwd, sync })))
+        .then(async (result) => {
+          await startOrRefreshWorkbench();
+          return enrichResult(result);
+        })
+        .then(onRebuild)
+        .catch((error) => {
+          onRebuild({ error });
+        });
     }, 100);
   });
 
   return {
     initialResult,
+    ready,
     close() {
       return cleanup();
     },
   };
 }
 
-export function unlinkSkill(name, { cwd = process.cwd() } = {}) {
+export function unlinkSkill(name, { cwd = process.cwd(), recursive = false } = {}) {
   const repoRoot = findRepoRoot(cwd);
+  const session = readDevSession(repoRoot);
+
+  if (recursive) {
+    if (!session || session.root_skill?.name !== name) {
+      throw new AgentpackError('Recursive unlink requires the active dev-session root skill', {
+        code: 'linked_skill_recursive_unlink_requires_root',
+        exitCode: EXIT_CODES.GENERAL,
+        nextSteps: session?.root_skill?.name
+          ? [{
+            action: 'run_command',
+            command: `agentpack skills unlink ${session.root_skill.name} --recursive`,
+            reason: 'Recursive unlink in v1 only works for the recorded dev-session root skill',
+          }]
+          : buildDevSessionNextSteps('agentpack skills dev cleanup --force'),
+        details: {
+          rootSkill: session?.root_skill?.name || null,
+        },
+      });
+    }
+
+    const removed = removeSkillLinksByPaths(repoRoot, session.links || [], normalizeDisplayPath);
+    removeDevSession(repoRoot);
+    return {
+      name,
+      unlinked: removed.length > 0,
+      removed,
+    };
+  }
+
   const existing = [
     join(repoRoot, '.claude', 'skills', name),
     join(repoRoot, '.agents', 'skills', name),
@@ -365,6 +557,43 @@ export function unlinkSkill(name, { cwd = process.cwd() } = {}) {
   };
 }
 
+export function cleanupSkillDevSession({ cwd = process.cwd(), force = false } = {}) {
+  const repoRoot = findRepoRoot(cwd);
+  const session = readDevSession(repoRoot);
+  if (!session) {
+    return {
+      cleaned: false,
+      active: false,
+      removed: [],
+    };
+  }
+
+  if (!force && session.status === 'active' && isProcessAlive(session.pid)) {
+    throw new AgentpackError('A skills dev session is still active in this repo', {
+      code: 'skills_dev_session_active',
+      exitCode: EXIT_CODES.GENERAL,
+      nextSteps: [
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup'),
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup --force'),
+      ],
+      details: {
+        rootSkill: session.root_skill?.name || null,
+        pid: session.pid,
+        startedAt: session.started_at || null,
+      },
+    });
+  }
+
+  const result = cleanupRecordedDevSession(repoRoot, session, 'stale');
+  return {
+    cleaned: true,
+    active: false,
+    forced: force,
+    name: session.root_skill?.name || null,
+    removed: result.removed,
+  };
+}
+
 function buildValidateNextSteps(packageMetadata, valid) {
   if (!valid || !packageMetadata.packageName) return [];
 

package/src/utils/errors.js

@@ -14,18 +14,31 @@ export const EXIT_CODES = {
  * Carries a machine-readable code and mapped exit code.
  */
 export class AgentpackError extends Error {
-  constructor(message, { code, exitCode = EXIT_CODES.GENERAL, suggestion } = {}) {
+  constructor(message, {
+    code,
+    exitCode = EXIT_CODES.GENERAL,
+    suggestion,
+    path,
+    nextSteps,
+    details,
+  } = {}) {
     super(message);
     this.name = 'AgentpackError';
     this.code = code || 'general_error';
     this.exitCode = exitCode;
     this.suggestion = suggestion;
+    this.path = path;
+    this.nextSteps = nextSteps || [];
+    this.details = details || {};
   }
 
   toJSON() {
     return {
       error: this.code,
       message: this.message,
+      ...(this.path && { path: this.path }),
+      ...(this.nextSteps.length > 0 && { nextSteps: this.nextSteps }),
+      ...(Object.keys(this.details).length > 0 && { details: this.details }),
       ...(this.suggestion && { suggestion: this.suggestion }),
     };
   }
@@ -58,6 +71,25 @@ export class NotFoundError extends AgentpackError {
 export function formatError(err) {
   if (err instanceof AgentpackError) {
     let msg = `Error: ${err.message}`;
+    if (err.path) {
+      msg += `\nPath: ${err.path}`;
+    }
+    if (err.nextSteps?.length) {
+      for (const step of err.nextSteps) {
+        const actionLabel = step.action === 'create_file'
+          ? `Create ${step.path}`
+          : step.action === 'edit_file'
+            ? `Edit ${step.path}`
+            : step.reason;
+        msg += `\nNext: ${actionLabel}`;
+        if (step.reason && step.reason !== actionLabel) {
+          msg += `\nWhy: ${step.reason}`;
+        }
+        if (step.example) {
+          msg += `\nExample:\n${JSON.stringify(step.example, null, 2)}`;
+        }
+      }
+    }
     if (err.suggestion) {
       msg += `\n\nSuggestion: ${err.suggestion}`;
     }