harden validation and Yarn PnP errors

Author: LadyBluenotes

packages/intent/src/commands/validate.ts

@@ -1,5 +1,5 @@
 import { appendFileSync, existsSync, readFileSync } from 'node:fs'
-import { join, relative, resolve, sep } from 'node:path'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { fail, isCliFailure } from '../cli-error.js'
 import { printWarnings } from '../cli-support.js'
 import {
@@ -13,10 +13,17 @@ interface ValidationError {
   message: string
 }
 
+interface ValidationWarning {
+  file: string
+  message: string
+}
+
 export interface ValidateCommandOptions {
   githubSummary?: boolean
 }
 
+const agentSkillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
 function buildValidationFailure(
   errors: Array<ValidationError>,
   warnings: Array<string>,
@@ -83,6 +90,116 @@ function collectPackagingWarnings(context: ProjectContext): Array<string> {
   return warnings
 }
 
+function formatWarning({ file, message }: ValidationWarning): string {
+  return `${file}: ${message}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function collectAgentSkillSpecWarnings({
+  filePath,
+  fm,
+  rel,
+}: {
+  filePath: string
+  fm: Record<string, unknown>
+  rel: string
+}): Array<ValidationWarning> {
+  const warnings: Array<ValidationWarning> = []
+
+  if (typeof fm.name === 'string') {
+    if (fm.name.length > 64) {
+      warnings.push({
+        file: rel,
+        message: `Agent Skills spec warning: name exceeds 64 characters (${fm.name.length} chars)`,
+      })
+    }
+
+    for (const segment of fm.name.split('/')) {
+      if (!agentSkillNamePattern.test(segment)) {
+        warnings.push({
+          file: rel,
+          message:
+            'Agent Skills spec warning: each name segment should use lowercase letters, numbers, and single hyphens only',
+        })
+        break
+      }
+    }
+
+    const parentDir = basename(dirname(filePath))
+    if (!fm.name.includes('/') && fm.name !== parentDir) {
+      warnings.push({
+        file: rel,
+        message:
+          'Agent Skills spec warning: name should match the parent directory name',
+      })
+    }
+  }
+
+  if (
+    fm.license !== undefined &&
+    (typeof fm.license !== 'string' || fm.license.trim().length === 0)
+  ) {
+    warnings.push({
+      file: rel,
+      message: 'Agent Skills spec warning: license should be a non-empty string',
+    })
+  }
+
+  if (fm.compatibility !== undefined) {
+    if (
+      typeof fm.compatibility !== 'string' ||
+      fm.compatibility.trim().length === 0
+    ) {
+      warnings.push({
+        file: rel,
+        message:
+          'Agent Skills spec warning: compatibility should be a non-empty string',
+      })
+    } else if (fm.compatibility.length > 500) {
+      warnings.push({
+        file: rel,
+        message: `Agent Skills spec warning: compatibility exceeds 500 characters (${fm.compatibility.length} chars)`,
+      })
+    }
+  }
+
+  if (fm.metadata !== undefined) {
+    if (!isRecord(fm.metadata)) {
+      warnings.push({
+        file: rel,
+        message: 'Agent Skills spec warning: metadata should be a mapping',
+      })
+    } else {
+      const hasNonStringValue = Object.values(fm.metadata).some(
+        (value) => typeof value !== 'string',
+      )
+      if (hasNonStringValue) {
+        warnings.push({
+          file: rel,
+          message:
+            'Agent Skills spec warning: metadata values should be strings',
+        })
+      }
+    }
+  }
+
+  if (
+    fm['allowed-tools'] !== undefined &&
+    typeof fm['allowed-tools'] !== 'string'
+  ) {
+    warnings.push({
+      file: rel,
+      message:
+        'Agent Skills spec warning: allowed-tools should be a space-separated string',
+    })
+  }
+
+  return warnings
+}
+
 export async function runValidateCommand(
   dir?: string,
   options: ValidateCommandOptions = {},
@@ -206,6 +323,12 @@ async function runValidateCommandInternal(dir?: string): Promise<void> {
         })
       }
 
+      warnings.push(
+        ...collectAgentSkillSpecWarnings({ filePath, fm, rel }).map(
+          formatWarning,
+        ),
+      )
+
       const lineCount = content.split(/\r?\n/).length
       if (lineCount > 500) {
         errors.push({

packages/intent/src/scanner.ts

@@ -100,26 +100,33 @@ function loadPnpApi(root: string): PnpApi | null {
   const pnpPath = findPnpFile(root)
   if (!pnpPath) return null
 
-  const moduleApi = requireFromHere('node:module') as {
-    findPnpApi?: (lookupSource: string) => PnpApi | null
-  }
-  const foundApi = moduleApi.findPnpApi?.(root)
-  if (foundApi) return foundApi
+  try {
+    const moduleApi = requireFromHere('node:module') as {
+      findPnpApi?: (lookupSource: string) => PnpApi | null
+    }
+    const foundApi = moduleApi.findPnpApi?.(root)
+    if (foundApi) return foundApi
 
-  const pnpModule = requireFromHere(pnpPath) as PnpApi
-  if (typeof pnpModule.setup === 'function') {
-    pnpModule.setup()
-  }
+    const pnpModule = requireFromHere(pnpPath) as PnpApi
+    if (typeof pnpModule.setup === 'function') {
+      pnpModule.setup()
+    }
 
-  if (
-    typeof pnpModule.getDependencyTreeRoots === 'function' &&
-    typeof pnpModule.getPackageInformation === 'function'
-  ) {
-    return pnpModule
-  }
+    if (
+      typeof pnpModule.getDependencyTreeRoots === 'function' &&
+      typeof pnpModule.getPackageInformation === 'function'
+    ) {
+      return pnpModule
+    }
 
-  const projectRequire = createRequire(join(dirname(pnpPath), 'package.json'))
-  return projectRequire('pnpapi') as PnpApi
+    const projectRequire = createRequire(join(dirname(pnpPath), 'package.json'))
+    return projectRequire('pnpapi') as PnpApi
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new Error(
+      `Yarn PnP project detected, but Intent could not load Yarn's PnP API from ${pnpPath}: ${msg}`,
+    )
+  }
 }
 
 function getPnpLocatorKey(locator: PnpPackageLocator): string {

packages/intent/tests/cli.test.ts

@@ -1127,6 +1127,46 @@ describe('cli commands', () => {
     )
   })
 
+  it('keeps nested Intent skill names valid without Agent Skills spec warnings', async () => {
+    const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-nested-'))
+    tempDirs.push(root)
+
+    writeSkillMd(join(root, 'skills', 'core', 'setup'), {
+      name: 'core/setup',
+      description: 'Core setup concepts',
+    })
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 1 skill files — all passed')
+    expect(output).not.toContain('Agent Skills spec warning')
+  })
+
+  it('warns but does not fail for Agent Skills spec-incompatible names', async () => {
+    const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-spec-'))
+    tempDirs.push(root)
+
+    writeSkillMd(join(root, 'skills', 'PDF-Processing'), {
+      name: 'PDF-Processing',
+      description: 'PDF processing concepts',
+    })
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 1 skill files — all passed')
+    expect(output).toContain(
+      'Agent Skills spec warning: each name segment should use lowercase letters, numbers, and single hyphens only',
+    )
+  })
+
   it('validates package skills from repo root without root packaging warnings', async () => {
     const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-mono-'))
     tempDirs.push(root)
@@ -1361,7 +1401,7 @@ describe('cli commands', () => {
     }
   })
 
-  it('fails cleanly for unsupported yarn pnp projects', async () => {
+  it('fails cleanly when the Yarn PnP API cannot be loaded', async () => {
     const root = mkdtempSync(join(realTmpdir, 'intent-cli-pnp-'))
     tempDirs.push(root)
     writeJson(join(root, 'package.json'), { name: 'app', private: true })
@@ -1372,7 +1412,9 @@ describe('cli commands', () => {
 
     expect(exitCode).toBe(1)
     expect(errorSpy).toHaveBeenCalledWith(
-      'Installed-package scanning in Yarn PnP projects without node_modules is not yet supported. `intent validate` can still validate workspace skills; for list/load/install, add `nodeLinker: node-modules` to .yarnrc.yml or use --global-only.',
+      expect.stringContaining(
+        'Yarn PnP project detected, but Intent could not load Yarn',
+      ),
     )
   })