@alavida/agentpack 0.1.5 → 0.1.7

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

@@ -0,0 +1,116 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  buildCanonicalSkillRequirement,
+  normalizeDisplayPath,
+  readInstalledSkillExports,
+  readPackageMetadata,
+} from './skill-model.js';
+
+function isIgnoredEntry(name) {
+  return name === '.git' || name === 'node_modules' || name === '.agentpack';
+}
+
+function listSkillPackageDirs(repoRoot, { installed = false } = {}) {
+  const root = installed ? join(repoRoot, 'node_modules') : repoRoot;
+  if (!existsSync(root)) return [];
+
+  const stack = [root];
+  const results = [];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    let hasRootSkillFile = false;
+    let packageMetadata = null;
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!installed && isIgnoredEntry(entry.name)) continue;
+        stack.push(join(current, entry.name));
+        continue;
+      }
+
+      if (entry.name === 'SKILL.md') hasRootSkillFile = true;
+      if (entry.name !== 'package.json') continue;
+
+      try {
+        packageMetadata = readPackageMetadata(current);
+      } catch {
+        packageMetadata = null;
+      }
+    }
+
+    if (!packageMetadata?.packageName) continue;
+    if (packageMetadata.exportedSkills || hasRootSkillFile) {
+      results.push(current);
+    }
+  }
+
+  return results.sort();
+}
+
+function buildCatalogKey(packageName, exportedSkills, entry) {
+  if (!packageName) return null;
+  if (exportedSkills.length <= 1) return packageName;
+  return buildCanonicalSkillRequirement(packageName, entry.name);
+}
+
+export function readSkillPackage(repoRoot, packageDir, { origin = 'authored' } = {}) {
+  const packageMetadata = readPackageMetadata(packageDir);
+  if (!packageMetadata.packageName) return null;
+
+  const exportedSkills = readInstalledSkillExports(packageDir);
+  if (exportedSkills.length === 0) return null;
+
+  return {
+    origin,
+    packageDir,
+    packagePath: normalizeDisplayPath(repoRoot, packageDir),
+    packageName: packageMetadata.packageName,
+    packageVersion: packageMetadata.packageVersion,
+    packageMetadata,
+    exports: exportedSkills.map((entry) => ({
+      ...entry,
+      key: buildCatalogKey(packageMetadata.packageName, exportedSkills, entry),
+      packageName: packageMetadata.packageName,
+      packageVersion: packageMetadata.packageVersion,
+      packageDir,
+      packagePath: normalizeDisplayPath(repoRoot, packageDir),
+      skillDirPath: entry.skillDir,
+      skillFilePath: entry.skillFile,
+      skillPath: normalizeDisplayPath(repoRoot, entry.skillDir),
+      skillFile: normalizeDisplayPath(repoRoot, entry.skillFile),
+    })),
+  };
+}
+
+export function listAuthoredSkillPackages(repoRoot) {
+  return listSkillPackageDirs(repoRoot)
+    .map((packageDir) => {
+      try {
+        return readSkillPackage(repoRoot, packageDir);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function listInstalledSkillPackages(repoRoot) {
+  return listSkillPackageDirs(repoRoot, { installed: true })
+    .map((packageDir) => {
+      try {
+        return readSkillPackage(repoRoot, packageDir, { origin: 'installed' });
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}

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

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { NotFoundError, ValidationError } from '../../utils/errors.js';
 
 function parseScalar(value) {
@@ -149,6 +149,12 @@ export function parseSkillFrontmatterFile(skillFilePath) {
     status: typeof fields.metadata?.status === 'string' ? fields.metadata.status : null,
     replacement: typeof fields.metadata?.replacement === 'string' ? fields.metadata.replacement : null,
     message: typeof fields.metadata?.message === 'string' ? fields.metadata.message : null,
+    wraps: typeof fields.metadata?.wraps === 'string'
+      ? fields.metadata.wraps
+      : (typeof fields.wraps === 'string' ? fields.wraps : null),
+    overrides: Array.isArray(fields.metadata?.overrides)
+      ? fields.metadata.overrides
+      : (Array.isArray(fields.overrides) ? fields.overrides : []),
   };
 }
 
@@ -171,6 +177,7 @@ export function readPackageMetadata(packageDir) {
       files: null,
       repository: null,
       publishConfigRegistry: null,
+      exportedSkills: null,
     };
   }
 
@@ -183,5 +190,67 @@ export function readPackageMetadata(packageDir) {
     files: Array.isArray(pkg.files) ? pkg.files : null,
     repository: pkg.repository || null,
     publishConfigRegistry: pkg.publishConfig?.registry || null,
+    exportedSkills: pkg.agentpack?.skills || null,
   };
 }
+
+export function buildCanonicalSkillRequirement(packageName, skillName) {
+  if (!packageName || !skillName) return null;
+  return `${packageName}:${skillName}`;
+}
+
+export function readInstalledSkillExports(packageDir) {
+  const packageMetadata = readPackageMetadata(packageDir);
+  const exports = [];
+
+  if (packageMetadata.exportedSkills && typeof packageMetadata.exportedSkills === 'object') {
+    for (const [declaredName, entry] of Object.entries(packageMetadata.exportedSkills)) {
+      const relativeSkillFile = typeof entry === 'string' ? entry : entry?.path;
+      if (!relativeSkillFile) continue;
+
+      const skillFile = join(packageDir, relativeSkillFile);
+      if (!existsSync(skillFile)) continue;
+
+      const metadata = parseSkillFrontmatterFile(skillFile);
+      exports.push({
+        declaredName,
+        name: metadata.name,
+        description: metadata.description,
+        sources: metadata.sources,
+        requires: metadata.requires,
+        status: metadata.status,
+        replacement: metadata.replacement,
+        message: metadata.message,
+        wraps: metadata.wraps,
+        overrides: metadata.overrides,
+        skillDir: dirname(skillFile),
+        skillFile,
+        relativeSkillFile,
+      });
+    }
+  }
+
+  if (exports.length > 0) {
+    return exports.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  const rootSkillFile = join(packageDir, 'SKILL.md');
+  if (!existsSync(rootSkillFile)) return [];
+
+  const metadata = parseSkillFrontmatterFile(rootSkillFile);
+  return [{
+    declaredName: metadata.name,
+    name: metadata.name,
+    description: metadata.description,
+    sources: metadata.sources,
+    requires: metadata.requires,
+    status: metadata.status,
+    replacement: metadata.replacement,
+    message: metadata.message,
+    wraps: metadata.wraps,
+    overrides: metadata.overrides,
+    skillDir: packageDir,
+    skillFile: rootSkillFile,
+    relativeSkillFile: 'SKILL.md',
+  }];
+}

package/src/domain/skills/skill-target-resolution.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { listAuthoredSkillPackages, listInstalledSkillPackages } from './skill-catalog.js';
+import { NotFoundError, ValidationError } from '../../utils/errors.js';
+
+function dedupePackages(authoredPackages, installedPackages) {
+  const seen = new Set(authoredPackages.map((pkg) => pkg.packageName));
+  return [
+    ...authoredPackages,
+    ...installedPackages.filter((pkg) => !seen.has(pkg.packageName)),
+  ];
+}
+
+export function loadSkillTargetContext(repoRoot, {
+  includeAuthored = true,
+  includeInstalled = true,
+} = {}) {
+  const authoredPackages = includeAuthored ? listAuthoredSkillPackages(repoRoot) : [];
+  const installedPackages = includeInstalled ? listInstalledSkillPackages(repoRoot) : [];
+
+  return {
+    authoredPackages,
+    installedPackages,
+    packages: dedupePackages(authoredPackages, installedPackages),
+  };
+}
+
+function buildPackageResolution(pkg, source) {
+  return {
+    kind: 'package',
+    source,
+    package: pkg,
+    exports: pkg.exports,
+  };
+}
+
+function buildExportResolution(pkg, skillExport, source) {
+  return {
+    kind: 'export',
+    source,
+    package: pkg,
+    export: skillExport,
+    exports: [skillExport],
+  };
+}
+
+export function resolveSkillTarget(repoRoot, target, options = {}) {
+  const context = loadSkillTargetContext(repoRoot, options);
+  const { packages } = context;
+
+  if (typeof target !== 'string' || target.length === 0) {
+    throw new NotFoundError('skill not found', {
+      code: 'skill_not_found',
+      suggestion: `Target: ${target}`,
+    });
+  }
+
+  const absoluteTarget = isAbsolute(target) ? target : resolve(repoRoot, target);
+
+  if (existsSync(absoluteTarget)) {
+    for (const pkg of packages) {
+      if (pkg.packageDir === absoluteTarget) {
+        return buildPackageResolution(pkg, 'package_path');
+      }
+
+      for (const skillExport of pkg.exports) {
+        if (skillExport.skillDirPath === absoluteTarget) {
+          return buildExportResolution(pkg, skillExport, 'skill_path');
+        }
+        if (skillExport.skillFilePath === absoluteTarget) {
+          return buildExportResolution(pkg, skillExport, 'skill_file');
+        }
+      }
+    }
+  }
+
+  const pkg = packages.find((entry) => entry.packageName === target);
+  if (pkg) {
+    return buildPackageResolution(pkg, 'package_name');
+  }
+
+  throw new NotFoundError('skill not found', {
+    code: 'skill_not_found',
+    suggestion: `Target: ${target}`,
+  });
+}
+
+export function resolveSingleSkillTarget(repoRoot, target, options = {}) {
+  const resolved = resolveSkillTarget(repoRoot, target, options);
+
+  if (resolved.kind === 'export') return resolved;
+  if (resolved.exports.length === 1) {
+    return buildExportResolution(resolved.package, resolved.exports[0], resolved.source);
+  }
+
+  throw new ValidationError('ambiguous skill target', {
+    code: 'ambiguous_skill_target',
+    suggestion: resolved.exports.map((entry) => entry.skillPath).join(', '),
+  });
+}

package/src/infrastructure/fs/user-config-repository.js

@@ -0,0 +1,40 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const DEFAULT_CONFIG = {
+  version: 1,
+  provider: 'github-packages',
+  scope: '@alavida-ai',
+  registry: 'https://npm.pkg.github.com',
+  verificationPackage: '@alavida-ai/agentpack-auth-probe',
+  managedNpmKeys: [],
+};
+
+function resolveConfigDir(env = process.env) {
+  const xdgConfigHome = env.XDG_CONFIG_HOME;
+  if (xdgConfigHome) return join(xdgConfigHome, 'agentpack');
+  return join(env.HOME || homedir(), '.config', 'agentpack');
+}
+
+export function getUserConfigPath({ env = process.env } = {}) {
+  return join(resolveConfigDir(env), 'config.json');
+}
+
+export function readUserConfig({ env = process.env } = {}) {
+  const configPath = getUserConfigPath({ env });
+  if (!existsSync(configPath)) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  return {
+    ...DEFAULT_CONFIG,
+    ...JSON.parse(readFileSync(configPath, 'utf-8')),
+  };
+}
+
+export function writeUserConfig(config, { env = process.env } = {}) {
+  const configPath = getUserConfigPath({ env });
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}

package/src/infrastructure/fs/user-credentials-repository.js

@@ -0,0 +1,30 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+function resolveConfigDir(env = process.env) {
+  const xdgConfigHome = env.XDG_CONFIG_HOME;
+  if (xdgConfigHome) return join(xdgConfigHome, 'agentpack');
+  return join(env.HOME || homedir(), '.config', 'agentpack');
+}
+
+export function getUserCredentialsPath({ env = process.env } = {}) {
+  return join(resolveConfigDir(env), 'credentials.json');
+}
+
+export function readUserCredentials({ env = process.env } = {}) {
+  const credentialsPath = getUserCredentialsPath({ env });
+  if (!existsSync(credentialsPath)) return null;
+  return JSON.parse(readFileSync(credentialsPath, 'utf-8'));
+}
+
+export function writeUserCredentials(credentials, { env = process.env } = {}) {
+  const credentialsPath = getUserCredentialsPath({ env });
+  mkdirSync(dirname(credentialsPath), { recursive: true });
+  writeFileSync(credentialsPath, JSON.stringify(credentials, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(credentialsPath, 0o600);
+}
+
+export function deleteUserCredentials({ env = process.env } = {}) {
+  rmSync(getUserCredentialsPath({ env }), { force: true });
+}

package/src/infrastructure/fs/user-npmrc-repository.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export function parseNpmrc(content) {
+  const config = {};
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+    const eqIndex = line.indexOf('=');
+    if (eqIndex === -1) continue;
+    const key = line.slice(0, eqIndex).trim();
+    const value = line.slice(eqIndex + 1).trim();
+    config[key] = value;
+  }
+  return config;
+}
+
+export function getUserNpmrcPath({ env = process.env } = {}) {
+  return join(env.HOME || homedir(), '.npmrc');
+}
+
+export function readUserNpmrc({ env = process.env } = {}) {
+  const npmrcPath = getUserNpmrcPath({ env });
+  if (!existsSync(npmrcPath)) return {};
+  return parseNpmrc(readFileSync(npmrcPath, 'utf-8'));
+}
+
+function upsertLine(lines, key, value) {
+  const prefix = `${key}=`;
+  const nextLine = `${key}=${value}`;
+  const index = lines.findIndex((line) => line.trim().startsWith(prefix));
+  if (index === -1) {
+    lines.push(nextLine);
+    return;
+  }
+  lines[index] = nextLine;
+}
+
+function removeLine(lines, key) {
+  const prefix = `${key}=`;
+  return lines.filter((line) => !line.trim().startsWith(prefix));
+}
+
+export function writeManagedNpmrcEntries({
+  entries,
+  env = process.env,
+} = {}) {
+  const npmrcPath = getUserNpmrcPath({ env });
+  const lines = existsSync(npmrcPath)
+    ? readFileSync(npmrcPath, 'utf-8').split('\n').filter((line, index, all) => !(index === all.length - 1 && line === ''))
+    : [];
+
+  for (const [key, value] of Object.entries(entries)) {
+    upsertLine(lines, key, value);
+  }
+
+  writeFileSync(npmrcPath, `${lines.join('\n')}\n`);
+}
+
+export function removeManagedNpmrcEntries({
+  keys,
+  env = process.env,
+} = {}) {
+  const npmrcPath = getUserNpmrcPath({ env });
+  if (!existsSync(npmrcPath)) return;
+
+  let lines = readFileSync(npmrcPath, 'utf-8').split('\n').filter((line, index, all) => !(index === all.length - 1 && line === ''));
+  for (const key of keys) {
+    lines = removeLine(lines, key);
+  }
+
+  writeFileSync(npmrcPath, `${lines.join('\n')}\n`);
+}

package/src/infrastructure/runtime/inspect-materialized-skills.js

@@ -0,0 +1,153 @@
+import { lstatSync, readlinkSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readDevSession } from '../fs/dev-session-repository.js';
+
+function readPathType(pathValue) {
+  try {
+    const stat = lstatSync(pathValue);
+    return {
+      exists: true,
+      isSymlink: stat.isSymbolicLink(),
+      type: stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other',
+    };
+  } catch {
+    return {
+      exists: false,
+      isSymlink: false,
+      type: null,
+    };
+  }
+}
+
+export function inspectRecordedMaterialization(repoRoot, {
+  target,
+  expectedSourcePath,
+  packageName,
+  runtimeName = null,
+} = {}) {
+  const absTarget = resolve(repoRoot, target);
+  const expectedTarget = resolve(repoRoot, expectedSourcePath);
+  const pathState = readPathType(absTarget);
+
+  if (!pathState.exists) {
+    return {
+      packageName,
+      runtimeName,
+      target,
+      expectedSourcePath,
+      code: 'missing_path',
+    };
+  }
+
+  if (!pathState.isSymlink) {
+    return {
+      packageName,
+      runtimeName,
+      target,
+      expectedSourcePath,
+      code: 'wrong_type',
+      actualType: pathState.type,
+    };
+  }
+
+  const rawLinkTarget = readlinkSync(absTarget);
+  const actualTarget = resolve(join(absTarget, '..'), rawLinkTarget);
+  if (actualTarget !== expectedTarget) {
+    return {
+      packageName,
+      runtimeName,
+      target,
+      expectedSourcePath,
+      code: 'wrong_target',
+      actualTarget,
+    };
+  }
+
+  const resolvedState = readPathType(actualTarget);
+  if (!resolvedState.exists) {
+    return {
+      packageName,
+      runtimeName,
+      target,
+      expectedSourcePath,
+      code: 'dangling_target',
+      actualTarget,
+    };
+  }
+
+  return null;
+}
+
+export function inspectMaterializedSkills(repoRoot, state) {
+  const runtimeDrift = [];
+  const ownedTargets = new Set();
+  const devSession = readDevSession(repoRoot);
+
+  if (devSession?.status === 'active') {
+    for (const target of devSession.links || []) {
+      ownedTargets.add(target);
+    }
+  }
+
+  for (const [packageName, install] of Object.entries(state.installs || {})) {
+    const issues = [];
+
+    for (const skill of install.skills || []) {
+      for (const materialization of skill.materializations || []) {
+        ownedTargets.add(materialization.target);
+        const issue = inspectRecordedMaterialization(repoRoot, {
+          target: materialization.target,
+          expectedSourcePath: skill.source_skill_path,
+          packageName,
+          runtimeName: skill.runtime_name,
+        });
+        if (issue) issues.push(issue);
+      }
+    }
+
+    if (issues.length > 0) {
+      runtimeDrift.push({
+        packageName,
+        issues,
+      });
+    }
+  }
+
+  const orphanedMaterializations = [];
+  for (const root of [
+    join(repoRoot, '.claude', 'skills'),
+    join(repoRoot, '.agents', 'skills'),
+  ]) {
+    let entries = [];
+    try {
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const relativeTarget = root.startsWith(join(repoRoot, '.claude'))
+        ? `.claude/skills/${entry.name}`
+        : `.agents/skills/${entry.name}`;
+      if (ownedTargets.has(relativeTarget)) continue;
+
+      const absPath = join(root, entry.name);
+      const pathState = readPathType(absPath);
+      orphanedMaterializations.push({
+        target: relativeTarget,
+        code: 'orphaned_materialization',
+        actualType: pathState.isSymlink ? 'symlink' : pathState.type,
+      });
+    }
+  }
+
+  runtimeDrift.sort((a, b) => a.packageName.localeCompare(b.packageName));
+  orphanedMaterializations.sort((a, b) => a.target.localeCompare(b.target));
+
+  return {
+    runtimeDriftCount: runtimeDrift.length,
+    runtimeDrift,
+    orphanedMaterializationCount: orphanedMaterializations.length,
+    orphanedMaterializations,
+  };
+}