@goodboyjs/cli 0.1.0 → 0.1.1

package/dist/commands/install.js

@@ -4,7 +4,7 @@ import { appendFile, readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
 import ora from 'ora';
 import { createRegistryAdapter } from '../lib/registry-adapter.js';
-import { readManifest, validateManifest } from '../lib/manifest.js';
+import { readManifest, validateManifestDetailed } from '../lib/manifest.js';
 import { requestConsent } from '../lib/consent.js';
 import { scanForSymlinks } from '../lib/fs-security.js';
 import { logger, sanitiseError } from '../lib/logger.js';
@@ -73,7 +73,11 @@ export async function installNamed(name, options, cwd) {
     let manifest;
     try {
         const data = await readManifest(join(skillPath, 'manifest.json'));
-        manifest = validateManifest(data);
+        const detailed = validateManifestDetailed(data);
+        manifest = detailed.manifest;
+        for (const warning of detailed.warnings) {
+            logger.warn(warning);
+        }
     }
     catch (err) {
         spinner.fail('Manifest validation failed');

package/dist/commands/upgrade.d.ts

@@ -1,2 +1,7 @@
 import { Command } from 'commander';
+export interface UpgradeOptions {
+    global?: boolean;
+}
+export declare function upgradeSkill(name: string, options: UpgradeOptions, cwd: string): Promise<void>;
+export declare function upgradeAll(options: UpgradeOptions, cwd: string): Promise<void>;
 export declare const upgradeCommand: Command;

package/dist/commands/upgrade.js

@@ -3,7 +3,7 @@ import { cpSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import ora from 'ora';
 import { createRegistryAdapter } from '../lib/registry-adapter.js';
-import { readManifest, validateManifest } from '../lib/manifest.js';
+import { readManifest, validateManifestDetailed } from '../lib/manifest.js';
 import { scanForSymlinks } from '../lib/fs-security.js';
 import { logger, sanitiseError } from '../lib/logger.js';
 import { SKILL_NAME_RE } from '../lib/validation.js';
@@ -12,7 +12,7 @@ import { getStorePath, getGoodboyHome } from '../lib/store.js';
 function getProjectSkillsPath(cwd) {
     return join(cwd, '.claude', 'skills');
 }
-async function upgradeSkill(name, options, cwd) {
+export async function upgradeSkill(name, options, cwd) {
     if (!SKILL_NAME_RE.test(name)) {
         throw new Error(`Invalid skill name: "${name}". Must match ^[a-z0-9-]+$.`);
     }
@@ -29,7 +29,11 @@ async function upgradeSkill(name, options, cwd) {
     let manifest;
     try {
         const data = await readManifest(join(skillPath, 'manifest.json'));
-        manifest = validateManifest(data);
+        const detailed = validateManifestDetailed(data);
+        manifest = detailed.manifest;
+        for (const warning of detailed.warnings) {
+            logger.warn(warning);
+        }
     }
     catch (err) {
         spinner.fail('Manifest validation failed');
@@ -67,7 +71,7 @@ async function upgradeSkill(name, options, cwd) {
     const from = lockedVersion !== null ? `${lockedVersion} → ` : '';
     spinner.succeed(`Upgraded "${name}" (${from}${manifest.version})`);
 }
-async function upgradeAll(options, cwd) {
+export async function upgradeAll(options, cwd) {
     const dir = options.global ? getGoodboyHome() : cwd;
     const goodboy = await readGoodBoyJson(dir);
     if (!goodboy) {

package/dist/lib/manifest.d.ts

@@ -1,4 +1,22 @@
 import type { GoodBoyManifest } from '../types/index.js';
+/**
+ * The manifest schema version this CLI validates strictly against. Manifests
+ * declaring a newer minor are tolerated (unknown top-level fields stripped,
+ * with a warning); a newer major is rejected. See validateManifestDetailed().
+ */
+export declare const KNOWN_SCHEMA_VERSION = "1.0.0";
 export declare function readManifest(filePath: string): Promise<unknown>;
+export interface ManifestValidationResult {
+    manifest: GoodBoyManifest;
+    warnings: string[];
+}
+/**
+ * Validates a manifest, tolerating a newer-minor `schema_version` than this
+ * CLI knows: unknown top-level fields are stripped (never mutating the
+ * caller's object) and a warning is returned instead of a hard failure. A
+ * newer major is always rejected. Manifests at or below the known minor take
+ * the exact same strict path as before this tolerance existed.
+ */
+export declare function validateManifestDetailed(data: unknown): ManifestValidationResult;
 export declare function validateManifest(data: unknown): GoodBoyManifest;
 export declare function writeManifest(filePath: string, data: GoodBoyManifest): Promise<void>;

package/dist/lib/manifest.js

@@ -7,16 +7,42 @@ const addFormats = addFormatsPkg.default;
 const _require = createRequire(import.meta.url);
 const MAX_MANIFEST_BYTES = 512 * 1024; // 512 KB
 const MAX_NESTING_DEPTH = 10;
+/**
+ * The manifest schema version this CLI validates strictly against. Manifests
+ * declaring a newer minor are tolerated (unknown top-level fields stripped,
+ * with a warning); a newer major is rejected. See validateManifestDetailed().
+ */
+export const KNOWN_SCHEMA_VERSION = '1.0.0';
+const SCHEMA_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+let _schema = null;
 let _validator = null;
+function getSchema() {
+    if (_schema)
+        return _schema;
+    _schema = _require('@goodboyjs/schema/src/manifest.schema.json');
+    return _schema;
+}
 function getValidator() {
     if (_validator)
         return _validator;
     const ajv = new Ajv({ strict: true, allErrors: true });
     addFormats(ajv);
-    const schema = _require('@goodboyjs/schema/src/manifest.schema.json');
-    _validator = ajv.compile(schema);
+    _validator = ajv.compile(getSchema());
     return _validator;
 }
+// Top-level property names the known schema recognizes. Used only to strip
+// unknown top-level fields from a newer-minor manifest before strict
+// validation — never to loosen validation of known fields.
+function getKnownTopLevelKeys() {
+    /* c8 ignore next -- the shipped schema always has a root "properties" key; ?? fallback is unreachable. Fail-closed if ever violated: an empty Set would strip every field, and every existing manifest test would fail immediately. */
+    const properties = (getSchema()['properties'] ?? {});
+    return new Set(Object.keys(properties));
+}
+function throwValidationError(validate) {
+    /* c8 ignore next 2 -- ajv always populates errors[] after a failed validate(); ?? fallbacks are unreachable */
+    const lines = (validate.errors ?? []).map((e) => `  ${e.instancePath || '(root)'}: ${e.message ?? 'validation failed'}`);
+    throw new Error(`Invalid manifest:\n${lines.join('\n')}`);
+}
 // Heuristic nesting depth check: counts opening brackets/braces.
 // This is intentionally fast and runs before JSON.parse() to guard against
 // deeply nested payloads that could exhaust the stack. Brackets inside
@@ -66,14 +92,61 @@ export async function readManifest(filePath) {
         throw new Error(`manifest.json contains invalid JSON`);
     }
 }
-export function validateManifest(data) {
+/**
+ * Validates a manifest, tolerating a newer-minor `schema_version` than this
+ * CLI knows: unknown top-level fields are stripped (never mutating the
+ * caller's object) and a warning is returned instead of a hard failure. A
+ * newer major is always rejected. Manifests at or below the known minor take
+ * the exact same strict path as before this tolerance existed.
+ */
+export function validateManifestDetailed(data) {
     const validate = getValidator();
-    if (!validate(data)) {
-        /* c8 ignore next 2 -- ajv always populates errors[] after a failed validate(); ?? fallbacks are unreachable */
-        const lines = (validate.errors ?? []).map((e) => `  ${e.instancePath || '(root)'}: ${e.message ?? 'validation failed'}`);
-        throw new Error(`Invalid manifest:\n${lines.join('\n')}`);
+    const knownParts = KNOWN_SCHEMA_VERSION.split('.').map(Number);
+    const knownMajor = knownParts[0];
+    const knownMinor = knownParts[1];
+    if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+        const rawVersion = data['schema_version'];
+        // The length gate (mirrors the schema's own maxLength: 32) must run before any
+        // interpolation of rawVersion into a message: an overlong value falls straight
+        // through to strict Ajv validation, which rejects it via maxLength without ever
+        // embedding the value in the error text.
+        if (typeof rawVersion === 'string' && rawVersion.length <= 32) {
+            const match = SCHEMA_VERSION_PATTERN.exec(rawVersion);
+            if (match) {
+                const major = Number(match[1]);
+                const minor = Number(match[2]);
+                if (major !== knownMajor) {
+                    const upgradeHint = major > knownMajor ? ' Upgrade GoodBoy to use this skill.' : '';
+                    throw new Error(`manifest declares schema ${rawVersion}; this version of GoodBoy supports ${knownMajor}.x manifests.${upgradeHint}`);
+                }
+                if (minor > knownMinor) {
+                    const known = getKnownTopLevelKeys();
+                    const stripped = {};
+                    for (const [key, value] of Object.entries(data)) {
+                        if (known.has(key))
+                            stripped[key] = value;
+                    }
+                    if (!validate(stripped))
+                        throwValidationError(validate);
+                    return {
+                        manifest: stripped,
+                        warnings: [
+                            `manifest uses schema ${rawVersion}; this GoodBoy CLI knows ${KNOWN_SCHEMA_VERSION}. Unknown fields were ignored — upgrade GoodBoy to use them.`,
+                        ],
+                    };
+                }
+                // minor <= knownMinor: fall through to strict validation below, unchanged.
+            }
+            // non-matching string: fall through; Ajv's pattern check reports the standard error.
+        }
+        // missing/non-string schema_version: fall through; Ajv's required/type check reports the standard error.
     }
-    return data;
+    if (!validate(data))
+        throwValidationError(validate);
+    return { manifest: data, warnings: [] };
+}
+export function validateManifest(data) {
+    return validateManifestDetailed(data).manifest;
 }
 export async function writeManifest(filePath, data) {
     const resolved = resolve(filePath);

package/dist/lib/skill-validator.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { readManifest, validateManifest } from './manifest.js';
+import { readManifest, validateManifestDetailed } from './manifest.js';
 import { logger } from './logger.js';
 function parseFrontmatter(content) {
     const lines = content.split('\n');
@@ -40,7 +40,11 @@ export async function validateSkillDirectory(skillPath) {
         try {
             const raw = await readManifest(manifestPath);
             try {
-                manifest = validateManifest(raw);
+                const detailed = validateManifestDetailed(raw);
+                manifest = detailed.manifest;
+                for (const warning of detailed.warnings) {
+                    issues.push({ severity: 'warning', message: warning });
+                }
             }
             catch (err) {
                 /* c8 ignore next */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodboyjs/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A personal skill registry and package manager for Claude Code and the Agent Skills ecosystem",
   "keywords": [
     "claude-code",