@alavida/agentpack 0.1.1 → 0.1.2

package/README.md

@@ -251,7 +251,11 @@ This package also ships an agent-facing skill under:
 node_modules/@alavida/agentpack/skills/agentpack-cli/SKILL.md
 ```
 
-If your repo uses TanStack Intent, you can map that shipped skill into your agent workflow so the agent knows how to use `agentpack` correctly inside downstream repos. This is optional. It is not required to use the CLI.
+Consumers can use TanStack Intent in their repos to map that shipped skill into their agent workflow so the agent knows how to use `agentpack` correctly.
+
+This is recommended if you want downstream coding agents to follow the right `agentpack` lifecycle automatically.
+
+It is still optional. You do not need Intent to install or run the CLI itself.
 
 ## Metadata Policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alavida/agentpack",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
   "type": "module",
   "bin": {

package/skills/agentpack-cli/SKILL.md

@@ -62,8 +62,15 @@ Key idea:
 - `SKILL.md.requires` is the source of truth
 - `package.json.dependencies` is the compiled mirror
 - `validate` and `dev` sync dependencies automatically
+- `skills validate` records the current source-hash snapshot in `.agentpack/build-state.json`
 - `skills dev` materializes the compiled skill artifact for runtime use
 
+Persistence rule:
+
+- commit `.agentpack/build-state.json` so stale detection works across GitHub, CI, and teammate machines
+- commit `.agentpack/catalog.json` in authoring repos
+- do not commit `.agentpack/install.json`
+
 Runtime notes:
 
 - after `skills dev` writes to `.claude/skills/` or `.agents/skills/`, start a fresh agent session if the current one was already running
@@ -112,6 +119,11 @@ Default flow:
 - `agentpack skills stale <skill>`
 - `agentpack skills validate <skill>`
 
+Key idea:
+
+- `skills stale` compares current source hashes to the last validated snapshot in `.agentpack/build-state.json`
+- if that file is not committed, stale detection will not persist across clones or CI runs
+
 ## Conceptual Frame
 
 When the user is reasoning about the model itself, explain agentpack this way:

package/skills/agentpack-cli/references/skill-lifecycle.md

@@ -42,9 +42,15 @@ Use this when the user is creating or changing a packaged skill in the same repo
 What each step means:
 
 - `inspect` explains what the skill currently is
-- `validate` checks package readiness and source existence
+- `validate` checks package readiness, source existence, and records the validated source snapshot in `.agentpack/build-state.json`
 - `dev` links the skill into `.claude/skills/` and `.agents/skills/` for local testing
 
+Important persistence behavior:
+
+- commit `.agentpack/build-state.json` if you want `skills stale` to work across GitHub, CI, and teammate machines
+- commit `.agentpack/catalog.json` in authoring repos
+- do not commit `.agentpack/install.json`
+
 Important runtime behavior:
 
 - if the agent session was already running before `skills dev`, start a fresh session so the runtime can rescan the linked skill
@@ -76,3 +82,17 @@ Consumption stage:
 - `skills env`
 
 Do not substitute one for the other.
+
+## Stale Detection Contract
+
+`skills stale` is not comparing against memory or local runtime state.
+
+It compares current source hashes against the last validated snapshot recorded in `.agentpack/build-state.json`.
+
+That means:
+
+1. run `agentpack skills validate <skill-dir>`
+2. commit the updated `.agentpack/build-state.json`
+3. later source changes can be detected by `agentpack skills stale`
+
+If the build-state file is not committed, stale detection will only work on the machine where validation was last run.

package/src/application/plugins/build-plugin.js

@@ -0,0 +1,5 @@
+import { buildPlugin } from '../../lib/plugins.js';
+
+export function buildPluginUseCase(target, options) {
+  return buildPlugin(target, options);
+}

package/src/application/plugins/inspect-plugin-bundle.js

@@ -0,0 +1,5 @@
+import { inspectPluginBundle } from '../../lib/plugins.js';
+
+export function inspectPluginBundleUseCase(target, options) {
+  return inspectPluginBundle(target, options);
+}

package/src/application/plugins/validate-plugin-bundle.js

@@ -0,0 +1,5 @@
+import { validatePluginBundle } from '../../lib/plugins.js';
+
+export function validatePluginBundleUseCase(target, options) {
+  return validatePluginBundle(target, options);
+}

package/src/application/skills/inspect-skill.js

@@ -0,0 +1,5 @@
+import { inspectSkill } from '../../lib/skills.js';
+
+export function inspectSkillUseCase(target, options) {
+  return inspectSkill(target, options);
+}

package/src/application/skills/list-stale-skills.js

@@ -0,0 +1,9 @@
+import { inspectStaleSkill, listStaleSkills } from '../../lib/skills.js';
+
+export function listStaleSkillsUseCase(options) {
+  return listStaleSkills(options);
+}
+
+export function inspectStaleSkillUseCase(target, options) {
+  return inspectStaleSkill(target, options);
+}

package/src/application/skills/validate-skills.js

@@ -0,0 +1,5 @@
+import { validateSkills } from '../../lib/skills.js';
+
+export function validateSkillsUseCase(target, options) {
+  return validateSkills(target, options);
+}

package/src/commands/plugin.js

@@ -1,5 +1,8 @@
 import { Command } from 'commander';
-import { buildPlugin, inspectPluginBundle, startPluginDev, validatePluginBundle } from '../lib/plugins.js';
+import { buildPluginUseCase } from '../application/plugins/build-plugin.js';
+import { inspectPluginBundleUseCase } from '../application/plugins/inspect-plugin-bundle.js';
+import { validatePluginBundleUseCase } from '../application/plugins/validate-plugin-bundle.js';
+import { startPluginDev } from '../lib/plugins.js';
 import { output } from '../utils/output.js';
 import { EXIT_CODES } from '../utils/errors.js';
 
@@ -13,7 +16,7 @@ export function pluginCommand() {
     .argument('<target>', 'Plugin directory path')
     .action((target, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = inspectPluginBundle(target);
+      const result = inspectPluginBundleUseCase(target);
 
       if (globalOpts.json) {
         output.json(result);
@@ -76,7 +79,7 @@ export function pluginCommand() {
     .argument('<target>', 'Plugin directory path')
     .action((target, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = validatePluginBundle(target);
+      const result = validatePluginBundleUseCase(target);
 
       if (globalOpts.json) {
         output.json(result);
@@ -114,7 +117,7 @@ export function pluginCommand() {
     .argument('<target>', 'Plugin directory path')
     .action((target, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = buildPlugin(target, { clean: opts.clean });
+      const result = buildPluginUseCase(target, { clean: opts.clean });
 
       if (globalOpts.json) {
         output.json(result);

package/src/commands/skills.js

@@ -1,20 +1,19 @@
 import { Command } from 'commander';
+import { inspectSkillUseCase } from '../application/skills/inspect-skill.js';
+import { inspectStaleSkillUseCase, listStaleSkillsUseCase } from '../application/skills/list-stale-skills.js';
+import { validateSkillsUseCase } from '../application/skills/validate-skills.js';
 import {
   inspectSkillDependencies,
   inspectMissingSkillDependencies,
   inspectSkillsStatus,
   inspectRegistryConfig,
-  inspectSkill,
   inspectSkillsEnv,
-  inspectStaleSkill,
   installSkills,
   listOutdatedSkills,
-  listStaleSkills,
   resolveInstallTargets,
   startSkillDev,
   unlinkSkill,
   uninstallSkills,
-  validateSkills,
 } from '../lib/skills.js';
 import { output } from '../utils/output.js';
 import { EXIT_CODES } from '../utils/errors.js';
@@ -250,7 +249,7 @@ export function skillsCommand() {
     .argument('<target>', 'Skill directory, SKILL.md path, or package name')
     .action((target, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = inspectSkill(target);
+      const result = inspectSkillUseCase(target);
 
       if (globalOpts.json) {
         output.json(result);
@@ -291,7 +290,7 @@ export function skillsCommand() {
       const globalOpts = command.optsWithGlobals();
 
       if (target) {
-        const result = inspectStaleSkill(target);
+        const result = inspectStaleSkillUseCase(target);
 
         if (globalOpts.json) {
           output.json(result);
@@ -310,7 +309,7 @@ export function skillsCommand() {
         return;
       }
 
-      const results = listStaleSkills();
+      const results = listStaleSkillsUseCase();
 
       if (globalOpts.json) {
         output.json({
@@ -337,7 +336,7 @@ export function skillsCommand() {
     .argument('[target]', 'Optional packaged skill directory, SKILL.md path, or package name')
     .action((target, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = validateSkills(target);
+      const result = validateSkillsUseCase(target);
 
       if (globalOpts.json) {
         output.json(

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

@@ -0,0 +1,136 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readSkillGraphNode(repoRoot, packageDir, {
+  directInstallNames = new Set(),
+  parseSkillFrontmatterFile,
+  readPackageMetadata,
+  findPackageDirByName,
+  normalizeDisplayPath,
+} = {}) {
+  const skillFile = join(packageDir, 'SKILL.md');
+  if (!existsSync(skillFile)) return null;
+
+  const skillMetadata = parseSkillFrontmatterFile(skillFile);
+  const packageMetadata = readPackageMetadata(packageDir);
+  if (!packageMetadata.packageName) return null;
+
+  const dependencyNames = Object.keys(packageMetadata.dependencies || {})
+    .filter((dependencyName) => {
+      const localPackageDir = findPackageDirByName(repoRoot, dependencyName);
+      if (localPackageDir && existsSync(join(localPackageDir, 'SKILL.md'))) return true;
+      const installedPackageDir = join(repoRoot, 'node_modules', ...dependencyName.split('/'));
+      return existsSync(join(installedPackageDir, 'SKILL.md'));
+    })
+    .sort((a, b) => a.localeCompare(b));
+
+  return {
+    name: skillMetadata.name,
+    packageName: packageMetadata.packageName,
+    packageVersion: packageMetadata.packageVersion,
+    skillPath: normalizeDisplayPath(repoRoot, packageDir),
+    skillFile: normalizeDisplayPath(repoRoot, skillFile),
+    direct: directInstallNames.has(packageMetadata.packageName),
+    dependencies: dependencyNames,
+  };
+}
+
+export function buildSkillGraph(repoRoot, packageDirs, options) {
+  const nodes = new Map();
+
+  for (const packageDir of packageDirs) {
+    const node = readSkillGraphNode(repoRoot, packageDir, options);
+    if (!node) continue;
+    nodes.set(node.packageName, node);
+  }
+
+  return nodes;
+}
+
+export function buildReverseDependencies(nodes) {
+  const reverse = new Map();
+  for (const packageName of nodes.keys()) reverse.set(packageName, []);
+
+  for (const node of nodes.values()) {
+    for (const dependencyName of node.dependencies || []) {
+      if (!reverse.has(dependencyName)) continue;
+      reverse.get(dependencyName).push(node.packageName);
+    }
+  }
+
+  for (const values of reverse.values()) values.sort((a, b) => a.localeCompare(b));
+  return reverse;
+}
+
+export function buildSkillStatusMap(nodes, staleSkills = new Set()) {
+  const cache = new Map();
+
+  function resolveStatus(packageName, seen = new Set()) {
+    if (cache.has(packageName)) return cache.get(packageName);
+    if (staleSkills.has(packageName)) {
+      cache.set(packageName, 'stale');
+      return 'stale';
+    }
+
+    if (seen.has(packageName)) return 'current';
+    seen.add(packageName);
+
+    const node = nodes.get(packageName);
+    if (!node) {
+      cache.set(packageName, null);
+      return null;
+    }
+
+    const dependencyStatuses = (node.dependencies || [])
+      .map((dependencyName) => resolveStatus(dependencyName, new Set(seen)))
+      .filter(Boolean);
+
+    const status = dependencyStatuses.some((value) => value === 'stale' || value === 'affected')
+      ? 'affected'
+      : 'current';
+
+    cache.set(packageName, status);
+    return status;
+  }
+
+  for (const packageName of nodes.keys()) {
+    resolveStatus(packageName);
+  }
+
+  return cache;
+}
+
+export function readNodeStatus(statusMap, packageName) {
+  if (!statusMap) return null;
+  return statusMap.get(packageName) || null;
+}
+
+export function resolveDependencyClosure(initialRequires, { resolveNode }) {
+  const seen = new Set();
+  const queue = [...initialRequires];
+  const resolved = [];
+  const unresolved = [];
+
+  while (queue.length > 0) {
+    const packageName = queue.shift();
+    if (seen.has(packageName)) continue;
+    seen.add(packageName);
+
+    const node = resolveNode(packageName);
+    if (!node) {
+      unresolved.push(packageName);
+      continue;
+    }
+
+    resolved.push(node);
+
+    for (const requirement of node.requires || []) {
+      if (!seen.has(requirement)) queue.push(requirement);
+    }
+  }
+
+  resolved.sort((a, b) => a.packageName.localeCompare(b.packageName));
+  unresolved.sort((a, b) => a.localeCompare(b));
+
+  return { resolved, unresolved };
+}

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

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { NotFoundError, ValidationError } from '../../utils/errors.js';
+
+function parseScalar(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function foldBlockScalar(lines, startIndex, baseIndent) {
+  const values = [];
+  let index = startIndex + 1;
+
+  while (index < lines.length) {
+    const rawLine = lines[index];
+    if (!rawLine.trim()) {
+      values.push('');
+      index += 1;
+      continue;
+    }
+
+    const indentMatch = rawLine.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+    if (indent <= baseIndent) break;
+
+    values.push(rawLine.slice(baseIndent + 2).trimEnd());
+    index += 1;
+  }
+
+  const folded = values
+    .join('\n')
+    .split('\n\n')
+    .map((chunk) => chunk.split('\n').join(' ').trim())
+    .filter((chunk, idx, arr) => chunk.length > 0 || idx < arr.length - 1)
+    .join('\n\n')
+    .trim();
+
+  return { value: folded, nextIndex: index };
+}
+
+function ensureContainer(target, key) {
+  if (!target[key] || typeof target[key] !== 'object' || Array.isArray(target[key])) {
+    target[key] = {};
+  }
+  return target[key];
+}
+
+export function parseSkillFrontmatterFile(skillFilePath) {
+  if (!existsSync(skillFilePath)) {
+    throw new NotFoundError(`skill file not found: ${skillFilePath}`, { code: 'skill_not_found' });
+  }
+
+  const content = readFileSync(skillFilePath, 'utf-8');
+  if (!content.startsWith('---\n')) {
+    throw new ValidationError('SKILL.md missing frontmatter', { code: 'missing_frontmatter' });
+  }
+
+  const fmEnd = content.indexOf('\n---', 4);
+  if (fmEnd === -1) {
+    throw new ValidationError('SKILL.md has unclosed frontmatter', { code: 'unclosed_frontmatter' });
+  }
+
+  const lines = content.slice(4, fmEnd).split('\n');
+  const fields = {};
+  let activeArrayKey = null;
+  let activeArrayTarget = null;
+  let activeParentKey = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const line = rawLine.trimEnd();
+    if (!line.trim()) continue;
+
+    const listMatch = rawLine.match(/^(\s*)-\s+(.+)$/);
+    if (listMatch && activeArrayKey && activeArrayTarget) {
+      activeArrayTarget[activeArrayKey].push(parseScalar(listMatch[2]));
+      continue;
+    }
+
+    const nestedKeyMatch = rawLine.match(/^\s{2}([A-Za-z][\w-]*):\s*(.*)$/);
+    if (nestedKeyMatch && activeParentKey) {
+      const [, key, value] = nestedKeyMatch;
+      const parent = ensureContainer(fields, activeParentKey);
+      if (value === '') {
+        parent[key] = [];
+        activeArrayKey = key;
+        activeArrayTarget = parent;
+        continue;
+      }
+
+      parent[key] = parseScalar(value);
+      activeArrayKey = null;
+      activeArrayTarget = null;
+      continue;
+    }
+
+    const keyMatch = rawLine.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (!keyMatch) continue;
+
+    const [, key, value] = keyMatch;
+    if (value === '>' || value === '|') {
+      const { value: blockValue, nextIndex } = foldBlockScalar(lines, index, 0);
+      fields[key] = blockValue;
+      activeParentKey = null;
+      activeArrayKey = null;
+      activeArrayTarget = null;
+      index = nextIndex - 1;
+      continue;
+    }
+
+    if (value === '') {
+      fields[key] = fields[key] && typeof fields[key] === 'object' && !Array.isArray(fields[key])
+        ? fields[key]
+        : [];
+      activeParentKey = key;
+      activeArrayKey = Array.isArray(fields[key]) ? key : null;
+      activeArrayTarget = Array.isArray(fields[key]) ? fields : null;
+      continue;
+    }
+
+    fields[key] = parseScalar(value);
+    activeParentKey = null;
+    activeArrayKey = null;
+    activeArrayTarget = null;
+  }
+
+  if (!fields.name) {
+    throw new ValidationError('SKILL.md frontmatter missing "name" field', { code: 'missing_name' });
+  }
+  if (!fields.description) {
+    throw new ValidationError('SKILL.md frontmatter missing "description" field', { code: 'missing_description' });
+  }
+
+  return {
+    name: fields.name,
+    description: fields.description,
+    sources: Array.isArray(fields.metadata?.sources)
+      ? fields.metadata.sources
+      : (Array.isArray(fields.sources) ? fields.sources : []),
+    requires: Array.isArray(fields.metadata?.requires)
+      ? fields.metadata.requires
+      : (Array.isArray(fields.requires) ? fields.requires : []),
+    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,
+  };
+}
+
+export function normalizeDisplayPath(repoRoot, absolutePath) {
+  return relative(repoRoot, absolutePath).split('\\').join('/');
+}
+
+export function normalizeRepoPath(repoRoot, absolutePath) {
+  return normalizeDisplayPath(repoRoot, absolutePath);
+}
+
+export function readPackageMetadata(packageDir) {
+  const packageJsonPath = join(packageDir, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return {
+      packageName: null,
+      packageVersion: null,
+      dependencies: {},
+      devDependencies: {},
+      files: null,
+      repository: null,
+      publishConfigRegistry: null,
+    };
+  }
+
+  const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+  return {
+    packageName: pkg.name || null,
+    packageVersion: pkg.version || null,
+    dependencies: pkg.dependencies || {},
+    devDependencies: pkg.devDependencies || {},
+    files: Array.isArray(pkg.files) ? pkg.files : null,
+    repository: pkg.repository || null,
+    publishConfigRegistry: pkg.publishConfig?.registry || null,
+  };
+}

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');
+}