@goodboyjs/cli 0.1.0 → 0.2.0

package/dist/commands/add.js

@@ -43,7 +43,7 @@ export const addCommand = new Command('add')
             formatValidationResult(result, dirName);
             throw new HandledFailure();
         }
-        if (result.issues.some((i) => i.severity === 'warning')) {
+        if (result.issues.some((i) => i.severity === 'warning' || i.severity === 'info')) {
             spinner.stop();
             formatValidationResult(result, dirName);
             spinner.start('Continuing...');

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/skill-version.d.ts

@@ -2,5 +2,6 @@ import { Command } from 'commander';
 declare const BUMP_LEVELS: readonly ["patch", "minor", "major"];
 type BumpLevel = (typeof BUMP_LEVELS)[number];
 export declare function bumpVersion(version: string, level: BumpLevel): string;
+export declare function assertWithin(target: string, base: string, label: string): void;
 export declare function registerSkillVersion(program: Command): void;
 export {};

package/dist/commands/skill-version.js

@@ -1,9 +1,9 @@
-import { cp } from 'node:fs/promises';
+import { cp, rm } from 'node:fs/promises';
 import { join, resolve, sep } from 'node:path';
 import ora from 'ora';
 import { getRegistryPath } from '../lib/registry.js';
 import { readRegistryEntry, writeRegistryEntry, resolveLatestVersion, resolveVersionPath, addVersionToEntry, } from '../lib/registry-entry.js';
-import { readManifest, writeManifest, validateManifest } from '../lib/manifest.js';
+import { readManifest, writeManifest, validateManifestDetailed, FIELD_INTRODUCED_IN, KNOWN_SCHEMA_VERSION, } from '../lib/manifest.js';
 import { SKILL_NAME_RE } from '../lib/validation.js';
 import { logger, sanitiseError } from '../lib/logger.js';
 const BUMP_LEVELS = ['patch', 'minor', 'major'];
@@ -15,7 +15,10 @@ export function bumpVersion(version, level) {
         case 'major': return `${major + 1}.0.0`;
     }
 }
-function assertWithin(target, base, label) {
+// Exported for direct unit testing: this guard is the security boundary in
+// front of the rm() cleanup on a failed version bump, so its throw path is
+// tested directly rather than left unreached-in-practice behind an ignore.
+export function assertWithin(target, base, label) {
     const resolvedTarget = resolve(target);
     const resolvedBase = resolve(base);
     if (!resolvedTarget.startsWith(resolvedBase + sep)) {
@@ -75,14 +78,71 @@ async function createNewVersion(skillName, bump) {
     assertWithin(newVersionDir, skillDir, 'new version path');
     const spinner = ora(`Creating ${skillName}@${newVersion}...`).start();
     try {
-        await cp(sourceVersionDir, newVersionDir, { recursive: true });
-        const manifestPath = join(newVersionDir, 'manifest.json');
-        const rawManifest = await readManifest(manifestPath);
-        const manifest = validateManifest(rawManifest);
-        manifest.version = newVersion;
-        await writeManifest(manifestPath, manifest);
-        const updatedEntry = addVersionToEntry(entry, newVersion, join('versions', newVersion));
-        await writeRegistryEntry(skillDir, updatedEntry);
+        // Validate-then-act: read the SOURCE manifest (byte-identical to what cp()
+        // would copy below) and decide whether this bump is even allowed BEFORE
+        // creating anything on disk. A refusal here leaves no orphaned
+        // versions/<newVersion>/ directory behind — nothing has been written yet.
+        const sourceManifestPath = join(sourceVersionDir, 'manifest.json');
+        const rawManifest = await readManifest(sourceManifestPath);
+        const { manifest, warnings } = validateManifestDetailed(rawManifest);
+        // Refuse rather than persist a lossy write. S1's tolerant path returns a
+        // manifest with unknown top-level fields already stripped and the warning
+        // about it discarded by the thin validateManifest() wrapper — "stripped
+        // fields are invisible downstream" is a safe guarantee for read-only
+        // consumers (list, skill-status, ...), but this is the one path that
+        // WRITES a validated manifest back to disk. Persisting the stripped
+        // object here would silently delete fields a newer-minor manifest
+        // declared and silently downgrade its schema_version, with no warning
+        // ever surfaced to the author. Fail closed instead: require a real
+        // GoodBoy upgrade before this skill can be bumped.
+        if (warnings.length > 0) {
+            throw new Error(`${skillName}/manifest.json declares schema_version ${manifest.schema_version}, which is newer than ` +
+                `this GoodBoy CLI knows (${KNOWN_SCHEMA_VERSION}). Upgrade GoodBoy to bump this skill — bumping now ` +
+                `would discard fields this version does not understand.`);
+        }
+        // Everything from here on mutates the filesystem. The "already exists"
+        // check above (entry.versions[newVersion]) already guarantees no
+        // registered version lives at newVersionDir, so anything found there from
+        // this point is either created by this call's own cp() or is debris from
+        // an earlier failed attempt at this exact, still-unregistered version
+        // number — never content worth protecting. That makes cleanup on failure
+        // safe unconditionally, with no extra existence guard needed beyond the
+        // registry check that already ran.
+        try {
+            await cp(sourceVersionDir, newVersionDir, { recursive: true });
+            const manifestPath = join(newVersionDir, 'manifest.json');
+            manifest.version = newVersion;
+            // Stamp the lowest schema version this manifest actually needs. This only
+            // ever runs on a manifest that already validated strictly (no warnings,
+            // checked above) — it normalizes an already-valid, possibly over-stamped
+            // manifest down to its minimum (e.g. requires present but stamped higher
+            // than 1.1.0 -> 1.1.0; requires absent -> 1.0.0). It does NOT rescue an
+            // under-stamped, invalid manifest (schema_version below what a field it
+            // uses requires) — that already failed above, in manifest.ts's own
+            // feature-stamping gate, before this function even reached the copy step;
+            // fixing it requires a manual schema_version edit, by design.
+            manifest.schema_version = manifest.requires ? FIELD_INTRODUCED_IN['requires'] : '1.0.0';
+            await writeManifest(manifestPath, manifest);
+            const updatedEntry = addVersionToEntry(entry, newVersion, join('versions', newVersion));
+            await writeRegistryEntry(skillDir, updatedEntry);
+        }
+        catch (writeErr) {
+            // The copy (or a write after it) failed partway through. Remove whatever
+            // landed at newVersionDir so a failed bump never leaves an orphaned,
+            // unregistered versions/<newVersion>/ directory behind. Re-assert the
+            // path is still inside skillDir immediately before removing it — never
+            // remove anything outside that boundary. A cleanup failure must never
+            // replace or hide the real error: it's caught in its own try/catch and
+            // only logged, and the ORIGINAL write error is always what propagates.
+            try {
+                assertWithin(newVersionDir, skillDir, 'new version path');
+                await rm(newVersionDir, { recursive: true, force: true });
+            }
+            catch (cleanupErr) {
+                logger.warn(`Failed to clean up "${newVersionDir}" after a failed bump: ${sanitiseError(cleanupErr)}`);
+            }
+            throw writeErr;
+        }
         spinner.succeed();
     }
     catch (err) {

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/consent.js

@@ -32,13 +32,26 @@ export function summarizePermissions(manifest) {
         .map((p) => PERMISSION_LABELS[p]);
 }
 export async function requestConsent(manifest) {
-    const lines = summarizePermissions(manifest);
-    if (lines.length === 0)
+    const permissionLines = summarizePermissions(manifest);
+    const secretNames = manifest.requires?.secrets ?? [];
+    // Explicit, not inferred: declared secrets imply the "env" permission (enforced
+    // as a hard error in manifest.ts), but this check must not rely on that — it
+    // decides whether to prompt at all, so it names both conditions directly.
+    if (permissionLines.length === 0 && secretNames.length === 0)
         return true;
     logger.info('');
-    logger.info(`Skill "${manifest.name}" requests the following permissions:`);
-    for (const line of lines) {
-        logger.info(`  • ${line}`);
+    if (permissionLines.length > 0) {
+        logger.info(`Skill "${manifest.name}" requests the following permissions:`);
+        for (const line of permissionLines) {
+            logger.info(`  • ${line}`);
+        }
+    }
+    if (secretNames.length > 0) {
+        logger.info('');
+        logger.info('Required secrets (names only — never resolved or read during install):');
+        for (const name of secretNames) {
+            logger.info(`  • ${name}`);
+        }
     }
     logger.info('');
     return confirm({

package/dist/lib/manifest.d.ts

@@ -1,4 +1,23 @@
 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.1.0";
+export declare const FIELD_INTRODUCED_IN: Record<string, string>;
 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,100 @@ 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.1.0';
+// Feature-driven stamping: a top-level field may only be used by a manifest
+// that declares a schema_version at or above the version that introduced it.
+// Without this, a manifest stamped e.g. "1.0.0" that uses a field only the
+// known schema (now on a later minor) recognizes would validate successfully
+// under Ajv — but an older, tolerant CLI that has never heard of the field
+// would reject it with a confusing additionalProperties error. Enforced here,
+// in code, because remediation text like this needs to name the exact field
+// and the exact version to stamp — not something Ajv's own error shapes give us.
+export const FIELD_INTRODUCED_IN = {
+    requires: '1.1.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')}`);
+}
+function parseSemverTriple(version) {
+    const match = SCHEMA_VERSION_PATTERN.exec(version);
+    /* c8 ignore next -- both call sites only ever pass an already-valid version string; null is a defensive return, not a reachable case */
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function isVersionAtLeast(declared, required) {
+    for (let i = 0; i < 3; i++) {
+        if (declared[i] !== required[i])
+            return declared[i] > required[i];
+    }
+    return true;
+}
+// Runs after a manifest has already passed Ajv validation (so schema_version
+// is guaranteed to match the schema's own pattern). Rejects a manifest that
+// uses a field its declared schema_version predates.
+function assertFeatureStamping(manifest) {
+    const declared = parseSemverTriple(manifest.schema_version);
+    /* c8 ignore next -- schema_version already satisfied Ajv's own pattern check by this point, so it always parses */
+    if (!declared)
+        return;
+    for (const key of Object.keys(manifest)) {
+        const introducedIn = FIELD_INTRODUCED_IN[key];
+        if (!introducedIn)
+            continue;
+        const required = parseSemverTriple(introducedIn);
+        if (!isVersionAtLeast(declared, required)) {
+            throw new Error(`manifest declares schema_version ${manifest.schema_version} but uses "${key}", which needs ${introducedIn}.\n` +
+                `Set "schema_version": "${introducedIn}" in manifest.json.`);
+        }
+    }
+}
+// Hard-error consistency rule (concept doc §7.1): requires.secrets is only
+// ever visible to a skill-installing user via the "env" permission on a
+// tolerant older CLI that doesn't know about `requires` at all — so the two
+// fields must never disagree. Fail closed rather than silently trusting one.
+function assertPermissionsConsistency(manifest) {
+    const secrets = manifest.requires?.secrets;
+    if (!secrets || secrets.length === 0)
+        return;
+    const permissions = manifest.permissions ?? [];
+    if (!permissions.includes('env')) {
+        throw new Error('manifest declares requires.secrets but "permissions" does not include "env".\n' +
+            'Secrets are delivered as environment variables; add "env" to permissions.');
+    }
+}
 // 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 +150,67 @@ 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);
+                    const manifest = stripped;
+                    assertFeatureStamping(manifest);
+                    assertPermissionsConsistency(manifest);
+                    return {
+                        manifest,
+                        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);
+    const manifest = data;
+    assertFeatureStamping(manifest);
+    assertPermissionsConsistency(manifest);
+    return { manifest, warnings: [] };
+}
+export function validateManifest(data) {
+    return validateManifestDetailed(data).manifest;
 }
 export async function writeManifest(filePath, data) {
     const resolved = resolve(filePath);

package/dist/lib/skill-validator.d.ts

@@ -1,4 +1,4 @@
-export type ValidationSeverity = 'error' | 'warning';
+export type ValidationSeverity = 'error' | 'warning' | 'info';
 export interface ValidationIssue {
     severity: ValidationSeverity;
     message: string;

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 */
@@ -68,6 +72,13 @@ export async function validateSkillDirectory(skillPath) {
         if (!manifest.tags || manifest.tags.length === 0) {
             issues.push({ severity: 'warning', message: 'manifest has no tags' });
         }
+        const secretCount = manifest.requires?.secrets.length ?? 0;
+        if (secretCount > 0) {
+            issues.push({
+                severity: 'info',
+                message: `declares ${secretCount} required secret${secretCount === 1 ? '' : 's'}`,
+            });
+        }
     }
     // --- SKILL.md checks ---
     const skillMdPath = join(skillPath, 'SKILL.md');
@@ -107,6 +118,7 @@ export async function validateSkillDirectory(skillPath) {
 export function formatValidationResult(result, skillName) {
     const errors = result.issues.filter((i) => i.severity === 'error');
     const warnings = result.issues.filter((i) => i.severity === 'warning');
+    const infos = result.issues.filter((i) => i.severity === 'info');
     if (errors.length > 0) {
         logger.error(`Validation errors for "${skillName}":`);
         for (const issue of errors) {
@@ -119,4 +131,7 @@ export function formatValidationResult(result, skillName) {
             logger.warn(`  • ${issue.message}`);
         }
     }
+    for (const issue of infos) {
+        logger.success(issue.message);
+    }
 }

package/package.json

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