jhste-skills 0.1.0

package/cli/install-actions/skills.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { directoryDigest, ensureDir, KIT_ROOT, listDirectories, nowIso } from '../shared.mjs';
+import { readJsonFile, validateJsonObject, validateStringArray } from '../json-file.mjs';
+
+export const SKILLS_MANIFEST_NAME = '.jhste-skills-manifest.json';
+export const MANIFEST_MANAGED_BY = 'jhste-skills';
+
+function vendoredSkillNames() {
+  const allowlistPath = path.join(KIT_ROOT, 'vendor', 'matt-pocock', 'allowlist.json');
+  return new Set(readJsonFile(allowlistPath, {
+    description: 'vendor/matt-pocock/allowlist.json',
+    validate: validateStringArray,
+  }));
+}
+
+export function skillNamesForSet(skillSet) {
+  const sourceRoot = path.join(KIT_ROOT, 'skills');
+  const all = listDirectories(sourceRoot);
+  const vendored = vendoredSkillNames();
+  if (skillSet === 'all') return all;
+  if (skillSet === 'vendor') return all.filter((name) => vendored.has(name));
+  return all.filter((name) => !vendored.has(name));
+}
+
+export function selectedSkillNames(plan) {
+  if (Array.isArray(plan.skillNames) && plan.skillNames.length > 0) return [...plan.skillNames];
+  return skillNamesForSet(plan.skillSet);
+}
+
+export function installedSkillStatus(skillsDir, skillSet) {
+  const expected = Array.isArray(skillSet) ? skillSet : skillNamesForSet(skillSet);
+  const missing = expected.filter((name) => !fs.existsSync(path.join(skillsDir, name, 'SKILL.md')));
+  return { expected, missing };
+}
+
+function manifestPath(skillsDir) {
+  return path.join(skillsDir, SKILLS_MANIFEST_NAME);
+}
+
+function loadSkillsManifest(skillsDir) {
+  const file = manifestPath(skillsDir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || parsed.managed_by !== MANIFEST_MANAGED_BY || typeof parsed.skills !== 'object' || Array.isArray(parsed.skills)) {
+      return { invalid: true, reason: `${SKILLS_MANIFEST_NAME} is not a valid ${MANIFEST_MANAGED_BY} manifest.` };
+    }
+    return parsed;
+  } catch (error) {
+    return { invalid: true, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function writeSkillsManifest(skillsDir, manifest) {
+  ensureDir(skillsDir);
+  fs.writeFileSync(manifestPath(skillsDir), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+function packageVersion() {
+  try {
+    return String(readJsonFile(path.join(KIT_ROOT, 'package.json'), {
+      description: 'package.json',
+      validate: validateJsonObject,
+    }).version || '0.0.0');
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function copyManagedSkill(source, destination, name, { force = false, allowUnmanagedOverwrite = false, manifest = null, nextManifest } = {}) {
+  if (!fs.existsSync(source)) return { status: 'missing-source', source, destination };
+  const sourceHash = directoryDigest(source);
+  const destinationExists = fs.existsSync(destination);
+  const destinationHash = destinationExists ? directoryDigest(destination) : null;
+  const manifestEntry = manifest?.skills?.[name] || null;
+  const manifestOwnsDestination = Boolean(manifestEntry);
+
+  function recordManaged() {
+    nextManifest.skills[name] = { digest: sourceHash };
+  }
+
+  if (!destinationExists) {
+    ensureDir(path.dirname(destination));
+    fs.cpSync(source, destination, { recursive: true });
+    recordManaged();
+    return { status: 'created', source, destination };
+  }
+  if (sourceHash === destinationHash) {
+    recordManaged();
+    return { status: 'unchanged', source, destination };
+  }
+  if (!force) return { status: 'skipped-existing-different', source, destination };
+  if (!manifestOwnsDestination && !allowUnmanagedOverwrite) {
+    return {
+      status: 'skipped-unmanaged-different',
+      source,
+      destination,
+      reason: `${path.basename(destination)} differs and is not recorded as managed by ${MANIFEST_MANAGED_BY}; pass --allow-unmanaged-skill-overwrite only after review`,
+    };
+  }
+  fs.rmSync(destination, { recursive: true, force: true });
+  fs.cpSync(source, destination, { recursive: true });
+  recordManaged();
+  return { status: manifestOwnsDestination ? 'overwritten-managed' : 'overwritten-unmanaged', source, destination };
+}
+
+function unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest) {
+  const out = [];
+  for (const name of selected) {
+    const source = path.join(sourceRoot, name);
+    const destination = path.join(skillsDir, name);
+    if (!fs.existsSync(source) || !fs.existsSync(destination)) continue;
+    if (directoryDigest(source) === directoryDigest(destination)) continue;
+    if (!currentManifest?.skills?.[name]) {
+      out.push({
+        status: 'skipped-unmanaged-different',
+        source,
+        destination,
+        reason: `${name} differs and is not recorded as managed by ${MANIFEST_MANAGED_BY}; pass --allow-unmanaged-skill-overwrite only after review`,
+      });
+    }
+  }
+  return out;
+}
+
+export function installSkills(skillsDir, { force = false, skillSet = 'core', allowUnmanagedOverwrite = false } = {}) {
+  const sourceRoot = path.join(KIT_ROOT, 'skills');
+  ensureDir(skillsDir);
+  const selected = Array.isArray(skillSet) ? skillSet : skillNamesForSet(skillSet);
+  const currentManifest = loadSkillsManifest(skillsDir);
+  if (currentManifest?.invalid) return [{ status: 'invalid-manifest', source: '', destination: manifestPath(skillsDir), reason: currentManifest.reason }];
+  const nextManifest = currentManifest || { managed_by: MANIFEST_MANAGED_BY, version: packageVersion(), installed_at: nowIso(), skills: {} };
+  nextManifest.managed_by = MANIFEST_MANAGED_BY;
+  nextManifest.version = packageVersion() || String(nextManifest.version || '0.0.0');
+  nextManifest.updated_at = nowIso();
+  nextManifest.skills ||= {};
+  const conflicts = force && !allowUnmanagedOverwrite ? unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest) : [];
+  if (conflicts.length) return conflicts;
+  const results = selected.map((name) => copyManagedSkill(path.join(sourceRoot, name), path.join(skillsDir, name), name, {
+    force,
+    allowUnmanagedOverwrite,
+    manifest: currentManifest,
+    nextManifest,
+  }));
+  writeSkillsManifest(skillsDir, nextManifest);
+  return results;
+}

package/cli/install-actions.mjs

@@ -0,0 +1,4 @@
+export { applyPlan } from './install-actions/apply-plan.mjs';
+export { bridgeTargetNames } from './install-actions/bridge-writer.mjs';
+export { preflightPlan } from './install-actions/preflight.mjs';
+export { printApplyResult } from './install-actions/output.mjs';

package/cli/install-flow/options.mjs

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseArgs } from '../shared.mjs';
+
+export const EXIT_CONFIG_FAILURE = 3;
+export const DEFAULT_LINE_LIMIT = 300;
+export const MODE_ALIASES = new Map([
+  ['minimal', 'minimal'],
+  ['min', 'minimal'],
+  ['1', 'minimal'],
+  ['normal', 'normal'],
+  ['default', 'normal'],
+  ['2', 'normal'],
+  ['full', 'full'],
+  ['3', 'full'],
+  ['custom', 'custom'],
+  ['c', 'custom'],
+  ['4', 'custom'],
+]);
+
+const SKILL_SET_ALIASES = new Map([
+  ['core', 'core'],
+  ['core-only', 'core'],
+  ['basic', 'core'],
+  ['vendor', 'vendor'],
+  ['vendor-only', 'vendor'],
+  ['all', 'all'],
+  ['full', 'all'],
+]);
+const BOOLEAN_OPTIONS = new Set(['yes', 'force', 'skip-hooks', 'no-bridge', 'skip-deep-scan', 'install-missing', 'no-line-limit', 'allow-unmanaged-skill-overwrite']);
+const VALUE_OPTIONS = new Set(['repo', 'skills-dir', 'hooks', 'hook', 'skill-set', 'mode', 'line-limit', 'line-limit-mode']);
+const HELP_OPTIONS = new Set(['help', 'h']);
+const COMMON_OPTIONS = new Set([...BOOLEAN_OPTIONS, ...VALUE_OPTIONS, ...HELP_OPTIONS]);
+const HOOK_TARGETS = new Set(['pre-commit', 'pre-push', 'all']);
+const HOOK_MODES = new Set(['advisory', 'blocking']);
+const LINE_LIMIT_MODES = new Set(['advisory', 'blocking', 'off']);
+
+function hasOption(args, key) {
+  return Object.prototype.hasOwnProperty.call(args, key);
+}
+
+function readBooleanOption(args, key, errors) {
+  if (!hasOption(args, key)) return false;
+  if (args[key] !== true) errors.push(`--${key} does not take a value.`);
+  return args[key] === true;
+}
+
+function readPathOption(args, key, errors) {
+  if (!hasOption(args, key)) return undefined;
+  const value = args[key];
+  if (value === true || String(value).trim() === '') {
+    errors.push(`--${key} requires a path value.`);
+    return undefined;
+  }
+  return String(value);
+}
+
+function normalizeMode(value, errors, { command }) {
+  if (value === undefined || value === true || String(value).trim() === '') return undefined;
+  const normalized = MODE_ALIASES.get(String(value).toLowerCase());
+  if (!normalized) {
+    errors.push(`--mode must be ${command === 'connect' ? 'normal, full, or custom' : 'minimal, normal, full, or custom'}.`);
+    return undefined;
+  }
+  if (command === 'connect' && normalized === 'minimal') {
+    errors.push('connect does not support --mode minimal because connect always changes the current project.');
+  }
+  return normalized;
+}
+
+function normalizeSkillSet(value, errors) {
+  const requested = value === undefined ? 'all' : String(value).toLowerCase();
+  const skillSet = SKILL_SET_ALIASES.get(requested);
+  if (!skillSet) errors.push('--skill-set must be core, vendor, or all.');
+  return skillSet || 'all';
+}
+
+function normalizeHookMode(value, errors) {
+  if (value === undefined) return undefined;
+  if (value === true) return 'advisory';
+  const requested = String(value || '').toLowerCase();
+  const hookMode = requested === 'true' ? 'advisory' : requested;
+  if (!HOOK_MODES.has(hookMode)) errors.push('--hooks must be advisory or blocking.');
+  return HOOK_MODES.has(hookMode) ? hookMode : undefined;
+}
+
+function normalizeHookTargets(value, errors) {
+  if (value === undefined) return undefined;
+  const requested = value === true ? 'pre-commit' : String(value || '').toLowerCase();
+  if (!HOOK_TARGETS.has(requested)) {
+    errors.push('--hook must be pre-commit, pre-push, or all.');
+    return undefined;
+  }
+  return requested === 'all' ? ['pre-commit', 'pre-push'] : [requested];
+}
+
+function normalizeLineLimit(value, errors) {
+  if (value === undefined) return DEFAULT_LINE_LIMIT;
+  if (value === true || String(value).trim() === '') {
+    errors.push('--line-limit requires a positive number.');
+    return DEFAULT_LINE_LIMIT;
+  }
+  const parsed = Number(String(value).trim());
+  if (!Number.isInteger(parsed) || parsed < 50 || parsed > 5000) {
+    errors.push('--line-limit must be an integer from 50 to 5000.');
+    return DEFAULT_LINE_LIMIT;
+  }
+  return parsed;
+}
+
+function normalizeLineLimitMode(value, errors) {
+  if (value === undefined) return undefined;
+  if (value === true || String(value).trim() === '') return 'advisory';
+  const normalized = String(value).toLowerCase();
+  if (!LINE_LIMIT_MODES.has(normalized)) {
+    errors.push('--line-limit-mode must be advisory, blocking, or off.');
+    return undefined;
+  }
+  return normalized;
+}
+
+export function usage(command = 'install') {
+  if (command === 'connect') {
+    console.log(`jhste-skills connect
+Usage:
+  jhste-skills connect [--mode normal|full|custom] [--repo <path>] [--skills-dir <path>]
+  jhste-skills connect --yes --mode normal|full [--install-missing] [--skip-hooks | --hooks advisory|blocking]
+Notes:
+  connect attaches an existing jhste-skills install to the current git repository.
+  connect requires a git repository and never overwrites non-managed hooks.
+  --mode minimal is intentionally invalid for connect.
+`);
+    return;
+  }
+  console.log(`jhste-skills install
+Usage:
+  jhste-skills install [--mode minimal|normal|full|custom] [--yes] [--repo <path>] [--skills-dir <path>]
+  jhste-skills install --yes [--skill-set core|vendor|all] [--line-limit <lines>] [--line-limit-mode advisory|blocking|off]
+  jhste-skills install --yes [--skip-hooks | --hooks advisory|blocking] [--hook pre-commit|pre-push|all]
+Notes:
+  Non-interactive installs require explicit --yes or -y.
+  The default mode is normal.
+  Normal installs all bundled skills by default; use --skill-set core for only jhste core skills.
+  Full installs all safe managed features; blocking hooks require an explicit interactive or CLI choice.
+  Line limit defaults to 300 lines when repo profile writing is enabled.
+  --skip-hooks and --hooks are mutually exclusive.
+  --force does not overwrite unmanaged skill directories; use --allow-unmanaged-skill-overwrite only after review.
+`);
+}
+
+export function normalizeOptions(argv, { command, cwd, nonInteractive }) {
+  const args = parseArgs(argv);
+  if (args.help || args.h) return { help: true, errors: [] };
+  const errors = [];
+  for (const key of Object.keys(args)) {
+    if (key !== '_' && !COMMON_OPTIONS.has(key)) errors.push(`unknown option --${key}.`);
+  }
+  if (args._.length > 0) errors.push(`unexpected positional argument: ${args._[0]}`);
+  const yes = readBooleanOption(args, 'yes', errors);
+  const force = readBooleanOption(args, 'force', errors);
+  const skipHooks = readBooleanOption(args, 'skip-hooks', errors);
+  const noBridge = readBooleanOption(args, 'no-bridge', errors);
+  const skipDeepScan = readBooleanOption(args, 'skip-deep-scan', errors);
+  const installMissing = readBooleanOption(args, 'install-missing', errors);
+  const noLineLimit = readBooleanOption(args, 'no-line-limit', errors);
+  const allowUnmanagedSkillOverwrite = readBooleanOption(args, 'allow-unmanaged-skill-overwrite', errors);
+  const repoInput = readPathOption(args, 'repo', errors);
+  const skillsDirInput = readPathOption(args, 'skills-dir', errors);
+  const mode = normalizeMode(hasOption(args, 'mode') ? args.mode : undefined, errors, { command });
+  const skillSet = normalizeSkillSet(hasOption(args, 'skill-set') ? args['skill-set'] : undefined, errors);
+  const explicitSkillSet = hasOption(args, 'skill-set');
+  const explicitHooks = hasOption(args, 'hooks');
+  const explicitHookTargets = hasOption(args, 'hook');
+  const hookMode = normalizeHookMode(explicitHooks ? args.hooks : undefined, errors);
+  const hookTargets = normalizeHookTargets(explicitHookTargets ? args.hook : undefined, errors);
+  const explicitLineLimit = hasOption(args, 'line-limit');
+  const explicitLineLimitMode = hasOption(args, 'line-limit-mode');
+  const lineLimit = normalizeLineLimit(explicitLineLimit ? args['line-limit'] : undefined, errors);
+  const lineLimitMode = normalizeLineLimitMode(explicitLineLimitMode ? args['line-limit-mode'] : undefined, errors);
+
+  if (skipHooks && explicitHooks) errors.push('--skip-hooks and --hooks are mutually exclusive.');
+  if (skipHooks && explicitHookTargets) errors.push('--skip-hooks and --hook are mutually exclusive.');
+  if (noLineLimit && explicitLineLimit) errors.push('--no-line-limit and --line-limit are mutually exclusive.');
+  if (noLineLimit && explicitLineLimitMode && lineLimitMode !== 'off') errors.push('--no-line-limit conflicts with --line-limit-mode unless it is off.');
+  if (skipHooks && lineLimitMode === 'blocking') errors.push('--line-limit-mode blocking requires managed hooks; do not combine it with --skip-hooks.');
+
+  const repoStart = path.resolve(repoInput || cwd);
+  if (repoInput) {
+    try {
+      if (!fs.statSync(repoStart).isDirectory()) errors.push(`--repo must be a directory: ${repoInput}`);
+    } catch {
+      errors.push(`--repo path does not exist: ${repoInput}`);
+    }
+  }
+
+  const skillsDir = path.resolve(skillsDirInput || path.join(os.homedir(), '.jhste', 'skills'));
+  if (fs.existsSync(skillsDir) && !fs.statSync(skillsDir).isDirectory()) {
+    errors.push(`--skills-dir must be a directory: ${skillsDirInput || skillsDir}`);
+  }
+
+  if (nonInteractive && !yes) errors.push(`non-interactive ${command} requires explicit --yes or -y; refusing to change files.`);
+  if (yes && mode === 'custom') errors.push('--mode custom requires interactive answers; do not combine it with --yes.');
+  if (nonInteractive && mode === 'custom') errors.push('--mode custom requires an interactive terminal.');
+
+  return {
+    args,
+    command,
+    errors,
+    explicitHookTargets,
+    explicitHooks,
+    explicitMode: hasOption(args, 'mode'),
+    explicitRepo: Boolean(repoInput),
+    explicitLineLimit,
+    explicitLineLimitMode,
+    explicitSkillSet,
+    force,
+    hookMode,
+    hookTargets,
+    installMissing,
+    allowUnmanagedSkillOverwrite,
+    lineLimit,
+    lineLimitMode,
+    mode,
+    noBridge,
+    noLineLimit,
+    repoStart,
+    skillSet,
+    skillsDir,
+    skipDeepScan,
+    skipHooks,
+    yes,
+  };
+}

package/cli/install-flow/output.mjs

@@ -0,0 +1,106 @@
+import { ask, relativeDisplay } from '../shared.mjs';
+import { EXIT_CONFIG_FAILURE } from './options.mjs';
+
+function describeSkillSet(skillSet) {
+  if (skillSet === 'detected') return 'Currently installed skills';
+  if (skillSet === 'all') return 'Core features + all optional features';
+  if (skillSet === 'vendor') return 'Optional features only (advanced option)';
+  return 'Core features';
+}
+
+function describeHookMode(mode) {
+  return mode === 'blocking' ? 'Block on detected issues' : 'Show warnings only';
+}
+
+export function printPlanSummary(plan) {
+  const heading = {
+    connect: 'Connection plan',
+    install: 'Install plan',
+    sync: 'Sync plan',
+    update: 'Update plan',
+  }[plan.command] || 'Plan';
+  console.log(`\n${heading}:`);
+  console.log(`- Command: ${plan.command}`);
+  console.log(`- Mode: ${plan.mode}`);
+  if (plan.overrides.length) console.log(`- Applied overrides: ${plan.overrides.join(', ')}`);
+  console.log(`- Feature set: ${describeSkillSet(plan.skillSet)}`);
+  console.log(`- Skills directory: ${plan.skillsDir}`);
+  if (plan.preflight.skills.enabled) {
+    console.log(`- Skills: ${plan.preflight.skills.expected} to install or update`);
+  } else if (plan.command === 'connect') {
+    if (plan.preflight.skills.action === 'install-missing') {
+      console.log(`- Skills: install missing after checking existing copies (${plan.preflight.skills.expected} required, missing=${plan.preflight.skills.missing.length})`);
+    } else {
+      console.log(`- Skills: use existing installation (${plan.preflight.skills.expected} required, missing=${plan.preflight.skills.missing.length})`);
+    }
+  } else {
+    console.log('- Skills: not installing');
+  }
+
+  if (plan.connectRepo) {
+    console.log(`- Current project: ${plan.repoRoot}`);
+    console.log(`- Config file: ${plan.preflight.profile.status}`);
+    if (plan.writeBridge) {
+      for (const bridge of plan.preflight.bridges) {
+        console.log(`- AI bridge: ${bridge.fileName} ${bridge.status}`);
+      }
+    } else {
+      console.log('- AI bridge: not adding');
+    }
+  } else {
+    console.log(`- Current project: ${plan.repoSkippedReason || 'not connecting'}`);
+  }
+
+  printLineLimitSummary(plan);
+  printHookSummary(plan);
+  if (plan.preflight.deepScan.enabled) {
+    console.log('- Deep scan: run now (may take a few minutes, does not modify source code)');
+    console.log(`  - Report: ${relativeDisplay(plan.repoRoot, plan.preflight.deepScan.report)}`);
+    console.log(`  - Recommended settings: ${relativeDisplay(plan.repoRoot, plan.preflight.deepScan.recommendedProfile)}`);
+  } else {
+    console.log('- Deep scan: not running');
+  }
+  console.log('- Left untouched: CI, package.json, lockfile, source code, non-managed hooks');
+  if (plan.force) {
+    console.log('- Note: --force refreshes only jhste-managed outputs and does not overwrite user-owned hooks, source, or CI files');
+  }
+}
+
+function printLineLimitSummary(plan) {
+  if (!plan.writeProfile || !plan.lineLimit) return;
+  if (plan.lineLimit.enabled) {
+    const behavior = plan.lineLimit.enforcement === 'blocking' ? 'block commits' : 'show warnings only';
+    console.log(`- Line limit: ${behavior} above ${plan.lineLimit.maxLines} lines`);
+  } else {
+    console.log('- Line limit: not used');
+  }
+}
+
+function printHookSummary(plan) {
+  if (plan.hooks.length) {
+    console.log('- Automatic checks:');
+    for (const hook of plan.preflight.hooks) {
+      const failOn = hook.failOn && hook.failOn !== 'none' ? `, fail-on=${hook.failOn}` : '';
+      console.log(`  - ${hook.target}: ${describeHookMode(hook.mode)}${failOn} (${hook.status})`);
+    }
+  } else {
+    console.log('- Automatic checks: not installing');
+  }
+}
+
+export async function confirmPlan(plan) {
+  if (plan.yes) {
+    console.log('\n--yes was provided, so this will continue without confirmation.');
+    return 'yes';
+  }
+  const answer = await ask('\nContinue? [Enter=yes / c=customize / q=cancel] ');
+  const normalized = String(answer).trim().toLowerCase();
+  if (normalized === 'q' || normalized === 'n' || normalized === 'no') return 'cancel';
+  if (normalized === 'c') return 'custom';
+  return 'yes';
+}
+
+export function printConfigErrors(command, errors) {
+  for (const error of errors) console.error(`jhste-skills ${command}: ${error}`);
+  process.exitCode = EXIT_CONFIG_FAILURE;
+}

package/cli/install-flow/plan-helpers.mjs

@@ -0,0 +1,29 @@
+import { DEFAULT_LINE_LIMIT } from './options.mjs';
+
+export function defaultLineLimit() {
+  return { enabled: true, maxLines: DEFAULT_LINE_LIMIT, enforcement: 'advisory' };
+}
+
+export function disabledLineLimit() {
+  return { enabled: false, maxLines: DEFAULT_LINE_LIMIT, enforcement: 'off' };
+}
+
+export function hookActions(targets, mode, failOn) {
+  return targets.map((target) => ({
+    target,
+    mode,
+    failOn: failOn || (mode === 'blocking' ? 'error' : 'none'),
+  }));
+}
+
+export function targetList(plan, fallback = ['pre-commit']) {
+  const existing = [...new Set((plan.hooks || []).map((hook) => hook.target))];
+  return existing.length ? existing : fallback;
+}
+
+export function applyLineLimitToHooks(plan, options) {
+  if (!plan.lineLimit?.enabled || plan.lineLimit.enforcement !== 'blocking') return;
+  if (options.skipHooks) return;
+  const targets = targetList(plan);
+  plan.hooks = hookActions(targets, 'blocking', 'warning');
+}