happyskills 1.1.0 → 1.2.1

package/src/commands/uninstall.js

@@ -93,4 +93,33 @@ const run = (args) => catch_errors('Uninstall failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'uninstall',
+	audience: 'consumer',
+	purpose:  'Remove one or more skills and prune their orphaned dependencies.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skills', required: true, type: 'string[]', pattern: '<owner>/<name>' } ],
+		flags: [
+			{ name: 'global',  alias: 'g',       type: 'boolean', default: false,     description: 'Remove from global scope' },
+			{ name: 'agents',                     type: 'string',  default: undefined, description: 'Target specific agents (comma-separated)' },
+			{ name: 'yes',     alias: 'y',        type: 'boolean', default: false,     description: 'Skip confirmation prompts' },
+			{ name: 'json',                        type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, status: string, removed: string[], orphans_pruned: string[] } | { skill: string, status: "failed", error: { code: string, message: string } }>',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+	],
+	examples: [
+		'happyskills uninstall acme/deploy-aws',
+		'happyskills uninstall acme/deploy-aws acme/monitor acme/logging',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/update.js

@@ -333,4 +333,43 @@ const run = (args) => catch_errors('Update failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'update',
+	audience: 'consumer',
+	purpose: 'Bring installed skills up to date by batch-checking the registry and re-installing only outdated skills.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [{ name: 'skill', required: false, type: 'string', pattern: '<owner>/<name>' }],
+		flags: [
+			{ name: 'all', type: 'boolean', default: false },
+			{ name: 'force', type: 'boolean', default: false },
+			{ name: 'global', type: 'boolean', default: false },
+			{ name: 'yes', type: 'boolean', default: false },
+			{ name: 'agents', type: 'string', default: null },
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, installed: string, latest: string, status: string }>',
+			outdated_count: 'number',
+			up_to_date_count: 'number',
+			drift_count: 'number',
+			updated: 'array<{ skill: string, from: string, to: string }>',
+			skipped: 'array<{ skill: string, reason: string, suggestion: string }>',
+			already_up_to_date: 'array<{ skill: string, version: string }>',
+			symlink_repairs: 'array',
+			errors: 'array<{ skill: string, message: string }>'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills update acme/deploy-aws',
+		'happyskills up --all -y --json'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/validate.js

@@ -232,4 +232,40 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	process.exit(has_errors ? EXIT_CODES.ERROR : EXIT_CODES.SUCCESS)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'validate',
+	audience: 'author',
+	purpose:  'Validate a local skill against all agentskills.io spec rules (structure, cross-file, file sizes, changelog, dependencies).',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill-name', required: true, type: 'string', pattern: '<skill-name>' },
+		],
+		flags: [
+			{ name: 'global', short: 'g', type: 'boolean', default: false },
+			{ name: 'json',   type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:          'string',
+			valid:          'boolean',
+			errors:         'array',
+			warnings:       'array',
+			checks_passed:  'number',
+			checks_failed:  'number',
+			checks_warned:  'number',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',      next_step: { kind: 'routing',   action: 'discover_schema'      } },
+		{ code: 'VALIDATION_FAILED', next_step: { kind: 'recovery',  action: 'fix_validation_errors' } },
+	],
+	examples: [
+		'happyskills validate my-skill',
+		'happyskills v my-skill --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/versions.js

@@ -89,4 +89,37 @@ const run = (args) => catch_errors('Versions failed', async () => {
 	print_table(['VERSION', 'PUBLISHED', 'COMMIT', 'MESSAGE'], rows)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run, extract_version, sort_refs }
+const schema = {
+	name:     'versions',
+	audience: 'consumer',
+	purpose:  'List all published versions of a skill from the registry, newest first.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'limit', type: 'number', default: null },
+			{ name: 'json',  type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:    'string',
+			count:    'number',
+			versions: 'array<{ version: string, ref: string, commit: string, message: string, published_at: string|null }>',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',  next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'NOT_FOUND' },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills versions acme/deploy-aws',
+		'happyskills versions acme/deploy-aws --limit 20 --json',
+	],
+}
+
+module.exports = { run, extract_version, sort_refs, schema }

package/src/commands/visibility.js

@@ -76,4 +76,36 @@ const run = (args) => catch_errors('Visibility failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'visibility',
+	audience: 'author',
+	purpose:  'Check or set a skill\'s visibility (public, private, workspace) in the registry.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill',      required: true,  type: 'string', pattern: '<owner>/<name>' },
+			{ name: 'visibility', required: false, type: 'string', pattern: 'public|private|workspace' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:      'string',
+			visibility: 'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login'           } },
+		{ code: 'NOT_FOUND' },
+	],
+	examples: [
+		'happyskills visibility acme/deploy-aws',
+		'happyskills visibility acme/deploy-aws public',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/whoami.js

@@ -67,4 +67,33 @@ const run = (args) => catch_errors('Whoami failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'whoami',
+	audience: 'account',
+	purpose:  'Show the currently authenticated user and their workspaces.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			username: 'string',
+			email: 'string',
+			workspaces: 'array'
+		}
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills whoami',
+		'happyskills whoami --json'
+	]
+}
+
+module.exports = { run, schema }

package/src/constants/error_codes.js

@@ -14,6 +14,7 @@
 // Auth & permission ────────────────────────────────────────────────────────
 const AUTH_REQUIRED          = 'AUTH_REQUIRED'
 const INVALID_CREDENTIALS    = 'INVALID_CREDENTIALS'
+const AUTH_FAILED            = 'AUTH_FAILED'
 const EXPIRED_TOKEN          = 'EXPIRED_TOKEN'
 const INTERACTIVE_REQUIRED   = 'INTERACTIVE_REQUIRED'
 const FORBIDDEN              = 'FORBIDDEN'
@@ -109,6 +110,13 @@ const WRITE_FAILED              = 'WRITE_FAILED'
 const PUBLISH_FAILED            = 'PUBLISH_FAILED'
 const RANKING_SCHEMA_MISMATCH   = 'RANKING_SCHEMA_MISMATCH'
 
+// pull --rebase pipeline (client-side, spec 260523-02) ──────────────────────
+const COMPARE_FAILED            = 'COMPARE_FAILED'
+const CLONE_BASE_FAILED         = 'CLONE_BASE_FAILED'
+const CLONE_REMOTE_FAILED       = 'CLONE_REMOTE_FAILED'
+const READ_LOCAL_FAILED         = 'READ_LOCAL_FAILED'
+const SWAP_FAILED               = 'SWAP_FAILED'
+
 // Internal ─────────────────────────────────────────────────────────────────
 const INTERNAL_ERROR        = 'INTERNAL_ERROR'
 const PERSIST_FAILED        = 'PERSIST_FAILED'
@@ -147,7 +155,8 @@ const NOT_COMMUNITY_LISTED    = 'NOT_COMMUNITY_LISTED'
 const UNKNOWN_CODE          = 'UNKNOWN_CODE'
 
 const ERROR_CODES = Object.freeze({
-	AUTH_REQUIRED, INVALID_CREDENTIALS, EXPIRED_TOKEN, INTERACTIVE_REQUIRED,
+	AUTH_REQUIRED, INVALID_CREDENTIALS, AUTH_FAILED, EXPIRED_TOKEN,
+	INTERACTIVE_REQUIRED,
 	FORBIDDEN, INSUFFICIENT_ACCESS, LAST_OWNER, ORG_RESTRICTED,
 	NETWORK_ERROR, RATE_LIMITED, DB_UNAVAILABLE, GITHUB_UNAVAILABLE,
 	EMBEDDING_UNAVAILABLE, REGISTRY_UNAVAILABLE,
@@ -172,6 +181,8 @@ const ERROR_CODES = Object.freeze({
 	AUTHORIZATION_PENDING,
 	COMMAND_NOT_FOUND, MIN_CLI_VERSION, SNAPSHOT_FAILED, WRITE_FAILED,
 	PUBLISH_FAILED, RANKING_SCHEMA_MISMATCH,
+	COMPARE_FAILED, CLONE_BASE_FAILED, CLONE_REMOTE_FAILED, READ_LOCAL_FAILED,
+	SWAP_FAILED,
 	INTERNAL_ERROR, PERSIST_FAILED, VERIFICATION_FAILED,
 	NO_COGNITO_USER, COGNITO_SYNC_FAILED, COGNITO_UNLINK_FAILED,
 	ALREADY_HAS_PASSWORD, EMAIL_ALIAS_CONFLICT, ALREADY_APPROVED,

package/src/constants/next_step_actions.js

@@ -31,6 +31,8 @@ const PROVIDE_CHANGELOG        = 'provide_changelog'
 const SELF_UPDATE              = 'self_update'
 const SHOW_FORMAT              = 'show_format'
 const RETRY_RANK               = 'retry_rank'
+const RETRY_OR_ABANDON         = 'retry_or_abandon'
+const REVIEW_PUBLISH_ERROR     = 'review_publish_error'
 
 // kind: clarification
 const CLARIFY_QUERY            = 'clarify_query'
@@ -45,6 +47,7 @@ const SPECIFY_WORKSPACE              = 'specify_workspace'
 const SPECIFY_BUMP_TYPE              = 'specify_bump_type'
 const RESOLVE_BUMP_DISAGREEMENT      = 'resolve_bump_disagreement'
 const PICK_VERSION                   = 'pick_version'
+const RESOLVE_UNKNOWN_DRIFT          = 'resolve_unknown_drift'
 
 // kind: confirmation
 const CONFIRM_DISCARD_OR_SNAPSHOT_FIRST = 'confirm_discard_or_snapshot_first'
@@ -72,6 +75,8 @@ const ACTION_KIND = Object.freeze({
 	[SELF_UPDATE]:                        RECOVERY,
 	[SHOW_FORMAT]:                        RECOVERY,
 	[RETRY_RANK]:                         RECOVERY,
+	[RETRY_OR_ABANDON]:                   RECOVERY,
+	[REVIEW_PUBLISH_ERROR]:               RECOVERY,
 
 	[CLARIFY_QUERY]:                      CLARIFICATION,
 
@@ -84,6 +89,7 @@ const ACTION_KIND = Object.freeze({
 	[SPECIFY_BUMP_TYPE]:                  DECISION,
 	[RESOLVE_BUMP_DISAGREEMENT]:          DECISION,
 	[PICK_VERSION]:                       DECISION,
+	[RESOLVE_UNKNOWN_DRIFT]:              DECISION,
 
 	[CONFIRM_DISCARD_OR_SNAPSHOT_FIRST]:  CONFIRMATION,
 	[CONFIRM_CASCADE]:                    CONFIRMATION,
@@ -101,10 +107,12 @@ const ACTION_KIND = Object.freeze({
 const NEXT_STEP_ACTIONS = Object.freeze({
 	LOGIN, RETRY, RECONCILE_FIRST, PULL_REBASE_FIRST, FIX_VALIDATION_ERRORS,
 	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT, RETRY_RANK,
+	RETRY_OR_ABANDON, REVIEW_PUBLISH_ERROR,
 	CLARIFY_QUERY,
 	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
 	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
 	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
+	RESOLVE_UNKNOWN_DRIFT,
 	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
 	PASS_YES_FLAG,
 	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT,

package/src/constants/next_step_by_error_code.js

@@ -59,6 +59,11 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		'Sign in to HappySkills, then re-run the command.',
 		{ commands: ['npx happyskills login --browser --json'] }
 	),
+	AUTH_FAILED: () => recovery(
+		LOGIN,
+		'The sign-in attempt did not complete. Start the login flow again, then re-run the command.',
+		{ commands: ['npx happyskills login --browser --json'] }
+	),
 	EXPIRED_TOKEN: () => recovery(
 		LOGIN,
 		'Your session has expired. Sign in again, then re-run the command.',

package/src/integration/schema.test.js

@@ -94,6 +94,37 @@ describe('happyskills schema --json', () => {
 		}
 	})
 
+	it('no command returns the stub purpose (anti-stub guard — spec 260602-01)', () => {
+		const { stdout } = run(['schema', '--json'])
+		const env = parse_envelope(stdout, 'schema --json anti-stub')
+		const stubbed = env.data.commands.filter(c => /no curated purpose/i.test(c.purpose))
+		assert.deepStrictEqual(
+			stubbed.map(c => c.name),
+			[],
+			`these commands still return the stub purpose and need a curated schema export: ${stubbed.map(c => c.name).join(', ')}`
+		)
+	})
+
+	it('every command carries a non-empty examples array of strings', () => {
+		const { stdout } = run(['schema', '--json'])
+		const env = parse_envelope(stdout, 'schema --json examples')
+		for (const cmd of env.data.commands) {
+			assert.ok(Array.isArray(cmd.examples) && cmd.examples.length > 0, `command.examples must be a non-empty array for ${cmd.name}`)
+			for (const ex of cmd.examples) {
+				assert.ok(typeof ex === 'string' && ex.length > 0, `command.examples[] entries must be non-empty strings for ${cmd.name}`)
+			}
+		}
+	})
+
+	it('every command.input exposes positional and flags arrays', () => {
+		const { stdout } = run(['schema', '--json'])
+		const env = parse_envelope(stdout, 'schema --json input shape')
+		for (const cmd of env.data.commands) {
+			assert.ok(Array.isArray(cmd.input.positional), `command.input.positional must be an array for ${cmd.name}`)
+			assert.ok(Array.isArray(cmd.input.flags), `command.input.flags must be an array for ${cmd.name}`)
+		}
+	})
+
 	it('every command.errors[].code is in the closed enum, and the kind/action pair is valid', () => {
 		const { stdout } = run(['schema', '--json'])
 		const env = parse_envelope(stdout, 'schema --json error refs')

package/src/ui/envelope.js

@@ -34,6 +34,9 @@ const DEFAULT_INSTRUCTIONS = {
 	retry:              'Transient failure. Retry shortly.',
 	reconcile_first:    'Drift must be resolved before this operation. Run reconcile, follow its next_step, then retry.',
 	pull_rebase_first:  'The local skill has diverged from the registry. Pull with --rebase, resolve any rejected patches, then retry.',
+	retry_or_abandon:   'The rebase step failed before any change landed. Retry the pull, or abandon and restore the snapshot.',
+	resolve_unknown_drift: 'Unrecognized drift subtype — surface the details to the principal for a manual decision.',
+	review_publish_error: 'The publish step failed. Inspect the wrapped publish error in context, resolve it, then retry.',
 	fix_validation_errors: 'Fix the listed validation errors and re-run.',
 	provide_changelog:  'CHANGELOG.md is missing the target version entry. Add it and re-run.',
 	self_update:        'Upgrade the happyskills CLI and re-run.',