jhste-skills 0.1.0

package/cli/install-flow/plan.mjs

@@ -0,0 +1,200 @@
+import { ask, findGitRootInfo } from '../shared.mjs';
+import { preflightPlan } from '../install-actions.mjs';
+import {
+  defaultLineLimit,
+  disabledLineLimit,
+  hookActions,
+  targetList,
+} from './plan-helpers.mjs';
+import {
+  askFullEnforcement,
+  askLineLimitPolicy,
+  chooseMode,
+  customInstallPlan,
+} from './prompts.mjs';
+
+function presetPlan(command, mode) {
+  if (command === 'connect') return presetConnectPlan(mode);
+  if (mode === 'minimal') {
+    return {
+      mode,
+      installSkills: true,
+      skillSet: 'core',
+      connectRepo: false,
+      writeProfile: false,
+      writeBridge: false,
+      hooks: [],
+      deepScan: false,
+      lineLimit: disabledLineLimit(),
+    };
+  }
+  if (mode === 'full') {
+    return {
+      mode,
+      installSkills: true,
+      skillSet: 'all',
+      connectRepo: true,
+      writeProfile: true,
+      writeBridge: true,
+      hooks: hookActions(['pre-commit', 'pre-push'], 'advisory'),
+      deepScan: true,
+      lineLimit: defaultLineLimit(),
+    };
+  }
+  return {
+    mode,
+    installSkills: true,
+    skillSet: 'all',
+    connectRepo: true,
+    writeProfile: true,
+    writeBridge: true,
+    hooks: hookActions(['pre-commit'], 'advisory'),
+    deepScan: false,
+    lineLimit: defaultLineLimit(),
+  };
+}
+
+function presetConnectPlan(mode) {
+  if (mode === 'full') {
+    return {
+      mode,
+      installSkills: false,
+      skillSet: 'all',
+      connectRepo: true,
+      writeProfile: true,
+      writeBridge: true,
+      hooks: hookActions(['pre-commit', 'pre-push'], 'advisory'),
+      deepScan: true,
+      lineLimit: defaultLineLimit(),
+    };
+  }
+  return {
+    mode,
+    installSkills: false,
+    skillSet: 'all',
+    connectRepo: true,
+    writeProfile: true,
+    writeBridge: true,
+    hooks: hookActions(['pre-commit'], 'advisory'),
+    deepScan: false,
+    lineLimit: defaultLineLimit(),
+  };
+}
+
+function applyOptionOverrides(plan, options) {
+  const overrides = [];
+  if (options.explicitSkillSet) {
+    plan.skillSet = options.skillSet;
+    overrides.push(`--skill-set ${options.skillSet}`);
+  }
+  if (options.noBridge) {
+    plan.writeBridge = false;
+    overrides.push('--no-bridge');
+  }
+  if (options.skipDeepScan) {
+    plan.deepScan = false;
+    overrides.push('--skip-deep-scan');
+  }
+  if (options.skipHooks) {
+    plan.hooks = [];
+    overrides.push('--skip-hooks');
+  } else if (options.explicitHooks || options.explicitHookTargets) {
+    plan.connectRepo = true;
+    const targets = options.hookTargets || targetList(plan);
+    const mode = options.hookMode || (plan.hooks[0]?.mode || 'advisory');
+    plan.hooks = hookActions(targets, mode);
+    if (options.explicitHooks) overrides.push(`--hooks ${mode}`);
+    if (options.explicitHookTargets) overrides.push(`--hook ${targets.length === 2 ? 'all' : targets[0]}`);
+  }
+  return overrides;
+}
+
+function attachCommonPlanState(plan, options, overrides) {
+  plan.command = options.command;
+  plan.force = options.force;
+  plan.allowUnmanagedSkillOverwrite = options.allowUnmanagedSkillOverwrite;
+  plan.installMissing = options.installMissing;
+  plan.overrides = overrides;
+  plan.skillsDir = options.skillsDir;
+  plan.repoStart = options.repoStart;
+  plan.explicitRepo = options.explicitRepo;
+  plan.yes = options.yes;
+  const repoInfo = findGitRootInfo(options.repoStart);
+  plan.repoInfo = repoInfo;
+  plan.repoRoot = repoInfo.repoRoot;
+  return repoInfo;
+}
+
+function validateRepoAttachment(plan, options, repoInfo) {
+  if (options.command === 'connect' && !repoInfo.isGitRepo) {
+    return { errors: [`connect requires a git repository: ${options.repoStart}`] };
+  }
+  if (plan.connectRepo && !repoInfo.isGitRepo) {
+    if (options.explicitRepo) {
+      return { errors: [`--repo must point inside a git repository for ${plan.mode} mode: ${options.repoStart}`] };
+    }
+    plan.repoSkippedReason = 'No current project detected, so project connection was skipped';
+    plan.connectRepo = false;
+    plan.writeProfile = false;
+    plan.writeBridge = false;
+    plan.hooks = [];
+    plan.deepScan = false;
+  }
+  if (!plan.connectRepo) {
+    plan.writeProfile = false;
+    plan.writeBridge = false;
+    plan.hooks = [];
+    plan.deepScan = false;
+  }
+  return null;
+}
+
+export { chooseMode };
+
+export async function resolvePlan(options) {
+  const selectedMode = await chooseMode(options);
+  if (selectedMode === 'cancel') return { cancelled: true };
+  if (options.command === 'connect' && selectedMode === 'minimal') {
+    return { errors: ['connect does not support minimal mode. Use install --mode minimal for computer-only setup.'] };
+  }
+
+  const plan = selectedMode === 'custom'
+    ? await customInstallPlan(options.command)
+    : presetPlan(options.command, selectedMode);
+  const overrides = applyOptionOverrides(plan, options);
+  const repoInfo = attachCommonPlanState(plan, options, overrides);
+  const repoError = validateRepoAttachment(plan, options, repoInfo);
+  if (repoError) return repoError;
+
+  await askFullEnforcement(plan, options);
+  await askLineLimitPolicy(plan, options);
+  plan.preflight = preflightPlan(plan);
+  return { plan };
+}
+
+export async function maybeInstallMissingForConnect(plan) {
+  const missing = plan.preflight.skills.missing;
+  if (plan.command !== 'connect' || missing.length === 0 || plan.installMissing) return { ok: true };
+  if (plan.yes) {
+    return {
+      ok: false,
+      errors: [
+        `connect requires ${plan.skillSet} skills but ${missing.length} are missing.`,
+        'Run `jhste-skills install` first or pass --install-missing to install missing skills explicitly.',
+      ],
+    };
+  }
+  const answer = await ask(`\n${missing.length} required skills are missing. Install them now? [y=install / Enter=cancel] `);
+  if (String(answer).trim().toLowerCase() === 'y') {
+    plan.installMissing = true;
+    plan.preflight.skills.action = 'install-missing';
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    errors: [
+      `connect requires ${plan.skillSet} skills but ${missing.length} are missing.`,
+      'Run `jhste-skills install` first or use `--install-missing`.',
+    ],
+  };
+}

package/cli/install-flow/prompts.mjs

@@ -0,0 +1,210 @@
+import { ask } from '../shared.mjs';
+import { DEFAULT_LINE_LIMIT, MODE_ALIASES } from './options.mjs';
+import {
+  applyLineLimitToHooks,
+  defaultLineLimit,
+  disabledLineLimit,
+  hookActions,
+} from './plan-helpers.mjs';
+
+function parseLineLimitAnswer(value) {
+  const normalized = String(value).trim();
+  if (!normalized) return DEFAULT_LINE_LIMIT;
+  const parsed = Number(normalized);
+  return Number.isInteger(parsed) && parsed >= 50 && parsed <= 5000 ? parsed : null;
+}
+
+function applyLineLimitOptions(plan, options) {
+  if (options.noLineLimit || options.lineLimitMode === 'off') {
+    plan.lineLimit = { enabled: false, maxLines: options.lineLimit, enforcement: 'off' };
+    plan.overrides?.push(options.noLineLimit ? '--no-line-limit' : '--line-limit-mode off');
+    return;
+  }
+  if (!plan.lineLimit) plan.lineLimit = defaultLineLimit();
+  if (options.explicitLineLimit) {
+    plan.lineLimit.maxLines = options.lineLimit;
+    plan.overrides?.push(`--line-limit ${options.lineLimit}`);
+  }
+  if (options.lineLimitMode) {
+    plan.lineLimit.enforcement = options.lineLimitMode;
+    plan.overrides?.push(`--line-limit-mode ${options.lineLimitMode}`);
+  }
+  if (options.explicitLineLimit || options.explicitLineLimitMode) applyLineLimitToHooks(plan, options);
+}
+
+export async function askLineLimitPolicy(plan, options) {
+  if (!plan.connectRepo || !plan.writeProfile) return;
+  applyLineLimitOptions(plan, options);
+  if (options.yes || options.noLineLimit || options.explicitLineLimit || options.explicitLineLimitMode) return;
+  const answer = await ask(`Configure a file length limit?
+Large files make review, edits, and test boundaries harder to reason about.
+
+1) Warn only at ${DEFAULT_LINE_LIMIT} lines
+2) Block commits at ${DEFAULT_LINE_LIMIT} lines
+3) Do not use a line limit
+4) Enter a custom line count
+
+Choice [Enter=1]: `);
+  const choice = String(answer).trim();
+  if (choice === '3') {
+    plan.lineLimit = disabledLineLimit();
+    return;
+  }
+  let enforcement = choice === '2' ? 'blocking' : 'advisory';
+  let maxLines = DEFAULT_LINE_LIMIT;
+  if (choice === '4') {
+    const limitAnswer = await ask(`Line limit [Enter=${DEFAULT_LINE_LIMIT}]: `);
+    const parsed = parseLineLimitAnswer(limitAnswer);
+    if (parsed === null) {
+      console.log(`Expected an integer between ${DEFAULT_LINE_LIMIT} and 5000. Using the default ${DEFAULT_LINE_LIMIT}-line limit.`);
+    } else {
+      maxLines = parsed;
+    }
+    const blockAnswer = await ask('Block commits when this limit is exceeded? [y=block / Enter=warn only] ');
+    if (String(blockAnswer).trim().toLowerCase() === 'y') enforcement = 'blocking';
+  }
+  plan.lineLimit = { enabled: true, maxLines, enforcement };
+  applyLineLimitToHooks(plan, options);
+}
+
+export async function chooseMode(options) {
+  if (options.mode) return options.mode;
+  if (options.yes) return 'normal';
+  while (true) {
+    const answer = await ask(`Choose an install mode.
+
+1) Minimal - Install the lightest setup
+2) Normal  - Use the recommended setup
+3) Full    - Install every safe optional feature
+4) Custom  - Choose settings manually
+
+Choice [Enter=Normal / q=cancel]: `);
+    const normalized = String(answer).trim().toLowerCase();
+    if (!normalized) return 'normal';
+    if (normalized === 'q' || normalized === 'quit' || normalized === 'n' || normalized === 'no') return 'cancel';
+    const selected = MODE_ALIASES.get(normalized);
+    if (selected) return selected;
+    console.log('Unknown choice. Enter 1, 2, 3, 4, or q.');
+  }
+}
+
+export async function customInstallPlan(command) {
+  const plan = {
+    mode: 'custom',
+    installSkills: command === 'install',
+    skillSet: 'all',
+    connectRepo: true,
+    writeProfile: true,
+    writeBridge: true,
+    hooks: hookActions(['pre-commit'], 'advisory'),
+    deepScan: false,
+    lineLimit: defaultLineLimit(),
+  };
+  await askCustomScope(plan, command);
+  if (plan.connectRepo) await askCustomProjectSettings(plan);
+  return plan;
+}
+
+async function askCustomScope(plan, command) {
+  if (command === 'install') {
+    const scope = await ask(`Where should this apply?
+
+1) This computer and the current project
+2) This computer only
+3) The current project only
+
+Choice [Enter=1]: `);
+    const normalizedScope = String(scope).trim();
+    if (normalizedScope === '2') {
+      plan.installSkills = true;
+      plan.connectRepo = false;
+      plan.writeProfile = false;
+      plan.writeBridge = false;
+      plan.hooks = [];
+      plan.deepScan = false;
+      plan.lineLimit = disabledLineLimit();
+    } else if (normalizedScope === '3') {
+      plan.installSkills = false;
+      plan.connectRepo = true;
+    }
+
+    if (plan.installSkills) {
+      const featureRange = await ask(`Choose the feature set to install.
+
+1) All bundled features
+2) jhste core guardrail features only
+
+Choice [Enter=1]: `);
+      if (String(featureRange).trim() === '2') plan.skillSet = 'core';
+    }
+    return;
+  }
+
+  plan.installSkills = false;
+  plan.connectRepo = true;
+  const featureRange = await ask(`Choose the feature set for the current project.
+
+1) All bundled features
+2) jhste core guardrail features only
+
+Choice [Enter=1]: `);
+  if (String(featureRange).trim() === '2') plan.skillSet = 'core';
+}
+
+async function askCustomProjectSettings(plan) {
+  const guidance = await ask(`Write project configuration files?
+
+1) Add the config file and AI bridge text
+2) Add the config file only
+3) Add nothing
+
+Choice [Enter=1]: `);
+  if (String(guidance).trim() === '2') {
+    plan.writeProfile = true;
+    plan.writeBridge = false;
+  } else if (String(guidance).trim() === '3') {
+    plan.writeProfile = false;
+    plan.writeBridge = false;
+  }
+
+  const checks = await ask(`Run automatic checks at commit time?
+
+1) Show warnings only
+2) Do not run checks
+3) Block the commit when clearly risky issues are detected
+
+Choice [Enter=1]: `);
+  if (String(checks).trim() === '2') plan.hooks = [];
+  if (String(checks).trim() === '3') plan.hooks = hookActions(['pre-commit'], 'blocking');
+
+  const scan = await ask(`Run a deep scan on the current project?
+This can take a few minutes and does not modify code.
+
+1) Later
+2) Run now
+
+Choice [Enter=1]: `);
+  if (String(scan).trim() === '2') plan.deepScan = true;
+}
+
+export async function askFullEnforcement(plan, options) {
+  if (options.yes || options.explicitHooks || options.explicitHookTargets || options.skipHooks) return;
+  if (plan.mode !== 'full' || !plan.connectRepo || plan.hooks.length === 0) return;
+  const answer = await ask(`Full mode preserves existing files and installs every safe optional feature.
+How should automatic check results be handled?
+
+1) Show warnings only - surface problems but do not block commit or push
+2) Block at commit time - stop the commit on clear errors
+3) Block at commit and push time - stricter enforcement
+
+Choice [Enter=1]: `);
+  const normalized = String(answer).trim();
+  if (normalized === '2') {
+    plan.hooks = [
+      ...hookActions(['pre-commit'], 'blocking'),
+      ...hookActions(['pre-push'], 'advisory'),
+    ];
+  } else if (normalized === '3') {
+    plan.hooks = hookActions(['pre-commit', 'pre-push'], 'blocking');
+  }
+}

package/cli/install-flow.mjs

@@ -0,0 +1,16 @@
+export { applyPlan, printApplyResult } from './install-actions.mjs';
+export {
+  EXIT_CONFIG_FAILURE,
+  normalizeOptions,
+  usage,
+} from './install-flow/options.mjs';
+export {
+  chooseMode,
+  maybeInstallMissingForConnect,
+  resolvePlan,
+} from './install-flow/plan.mjs';
+export {
+  confirmPlan,
+  printConfigErrors,
+  printPlanSummary,
+} from './install-flow/output.mjs';

package/cli/install.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import {
+  applyPlan,
+  confirmPlan,
+  EXIT_CONFIG_FAILURE,
+  maybeInstallMissingForConnect,
+  normalizeOptions,
+  printApplyResult,
+  printConfigErrors,
+  printPlanSummary,
+  resolvePlan,
+  usage,
+} from './install-flow.mjs';
+
+async function main() {
+  const nonInteractive = !process.stdin.isTTY;
+  const options = normalizeOptions(process.argv.slice(2), {
+    command: 'install',
+    cwd: process.cwd(),
+    nonInteractive,
+  });
+  if (options.help) {
+    usage('install');
+    return;
+  }
+  if (options.errors.length > 0) {
+    printConfigErrors('install', options.errors);
+    return;
+  }
+
+  let resolved = await resolvePlan(options);
+  if (resolved.cancelled) {
+    console.log('Install cancelled. No changes made.');
+    return;
+  }
+  if (resolved.errors?.length) {
+    printConfigErrors('install', resolved.errors);
+    return;
+  }
+  let { plan } = resolved;
+  printPlanSummary(plan);
+
+  let confirmation = await confirmPlan(plan);
+  if (confirmation === 'cancel') {
+    console.log('Install cancelled. No changes made.');
+    return;
+  }
+  if (confirmation === 'custom') {
+    resolved = await resolvePlan({ ...options, mode: 'custom', explicitMode: true });
+    if (resolved.errors?.length) {
+      printConfigErrors('install', resolved.errors);
+      return;
+    }
+    plan = resolved.plan;
+    printPlanSummary(plan);
+    confirmation = await confirmPlan(plan);
+    if (confirmation !== 'yes') {
+      console.log('Install cancelled. No changes made.');
+      return;
+    }
+  }
+
+  const missing = await maybeInstallMissingForConnect(plan);
+  if (!missing.ok) {
+    printConfigErrors('install', missing.errors);
+    return;
+  }
+
+  const result = applyPlan(plan);
+  printApplyResult(plan, result);
+  if (result.exitCode) process.exitCode = result.exitCode;
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(EXIT_CONFIG_FAILURE);
+});

package/cli/json-file.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+
+function describePath(file, description) {
+  return description || file;
+}
+
+export function parseJsonText(text, { description = 'JSON input', validate = null } = {}) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${description} is not valid JSON: ${message}`);
+  }
+  if (validate) {
+    const validationError = validate(value);
+    if (validationError) throw new Error(`${description} failed validation: ${validationError}`);
+  }
+  return value;
+}
+
+export function readJsonFile(file, { description, validate = null } = {}) {
+  return parseJsonText(fs.readFileSync(file, 'utf8'), {
+    description: describePath(file, description),
+    validate,
+  });
+}
+
+export function validateJsonObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? null
+    : 'expected a JSON object';
+}
+
+export function validateStringArray(value) {
+  if (!Array.isArray(value)) return 'expected a JSON array';
+  const invalidIndex = value.findIndex((item) => typeof item !== 'string' || item.trim() === '');
+  return invalidIndex === -1 ? null : `expected a non-empty string at index ${invalidIndex}`;
+}

package/cli/profile/loader.mjs

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseProfileText } from './parser.mjs';
+
+export function loadProfileConfig(repoRoot) {
+  const profilePath = path.join(repoRoot, '.jhste', 'profile.yaml');
+  if (!fs.existsSync(profilePath)) return { path: profilePath, exists: false, profile: parseProfileText('') };
+  return {
+    path: profilePath,
+    exists: true,
+    profile: parseProfileText(fs.readFileSync(profilePath, 'utf8')),
+  };
+}