@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/skills-apply.mjs

@@ -0,0 +1,280 @@
+/**
+ * lib/skills-apply.mjs — writes per-host skill filter configs from the
+ * project profile.
+ *
+ * The detection layer (lib/project-profile.mjs) is host-agnostic. This layer
+ * consumes a profile and writes host-specific configuration that scopes which
+ * skills/plugins auto-inject in the current project.
+ *
+ * Safety guarantees (org-in-a-box):
+ *   1. isProtectedSkill() from project-profile.mjs defines a NEVER-FILTER set
+ *      covering construct personas, cx-* specialists, cross-cutting skills,
+ *      role-domain namespaces (engineering:, product-management:, etc.), and
+ *      Claude Code dev infrastructure. These are always kept enabled.
+ *   2. The filter is *additive recommendation* — disabled plugins remain on
+ *      disk and can be called explicitly. We only remove them from automatic
+ *      per-turn injection.
+ *   3. A construct-native manifest (.cx/skills-profile.json) records the
+ *      decision so construct-mcp can read it at session start and surface
+ *      what was filtered.
+ *   4. Never overwrite an existing `.claude/settings.json` key the user set
+ *      manually — merge into disabledPlugins with de-dup.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import {
+  classifySkillRelevance,
+  detectProjectProfile,
+  enumerateInstalledSkills,
+  writeProfile,
+} from './project-profile.mjs';
+
+const SUPPORTED_HOSTS = new Set(['claude', 'opencode', 'codex', 'all']);
+
+function readJsonSafe(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+function writeJsonPretty(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function unionArrays(existing, incoming) {
+  const seen = new Set();
+  const result = [];
+  for (const arr of [existing, incoming]) {
+    for (const item of arr || []) {
+      if (seen.has(item)) continue;
+      seen.add(item);
+      result.push(item);
+    }
+  }
+  return result.sort();
+}
+
+/**
+ * Writes the construct-native project manifest to `<cwd>/.cx/skills-profile.json`.
+ * The authoritative record consumed by construct-mcp and any future per-host
+ * writers that want to re-derive the decision.
+ */
+export function writeConstructManifest(cwd, profile, classification) {
+  const path = join(cwd, '.cx', 'skills-profile.json');
+  const payload = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    profile: {
+      tags: profile.tags,
+      signals: profile.signals,
+    },
+    decision: {
+      relevant: classification.relevant,
+      irrelevant: classification.irrelevant,
+      unknown: classification.unknown,
+      protected: classification.protected || [],
+    },
+    // The "recommended disabled" list. Never includes protected skills.
+    // Hosts are expected to honor this as a scoping recommendation.
+    recommendedDisable: classification.irrelevant,
+  };
+  writeJsonPretty(path, payload);
+  return path;
+}
+
+/**
+ * Writes `<cwd>/.claude/construct-skills.json` — a construct-owned sidecar
+ * that records the recommended per-project scoping for Claude Code.
+ *
+ * Why a sidecar and not `settings.json`? Claude Code today only reads
+ * `permissions`, `hooks`, and `mcpServers` from settings.json. A
+ * `disabledPlugins` key would be ignored silently. Writing a sidecar is
+ * honest — it documents the recommendation without pretending the harness
+ * enforces it. The construct-mcp session-start path can read this sidecar
+ * and inject a "skills out of scope for this project" note.
+ *
+ * If Claude Code adds per-project plugin scoping in the future, the
+ * adapter will flip to writing the supported key(s) directly.
+ */
+export function writeClaudeHostConfig(cwd, classification) {
+  const path = join(cwd, '.claude', 'construct-skills.json');
+  writeJsonPretty(path, {
+    $comment: 'Construct-owned sidecar. Claude Code does not currently honor project-level skill scoping; this is advisory. construct-mcp can read this to surface out-of-scope skills at session start.',
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    source: '.cx/skills-profile.json',
+    recommendedDisable: classification.irrelevant,
+    protected: classification.protected || [],
+  });
+  return path;
+}
+
+/**
+ * Writes a Construct-owned OpenCode sidecar at `<cwd>/.opencode/construct-skills.json`.
+ *
+ * OpenCode will eagerly parse `<cwd>/opencode.json` as first-party config, so
+ * Construct must not write custom top-level keys there. The session-start
+ * adapter can read this sidecar and surface skill-scoping guidance without
+ * breaking OpenCode's schema validation.
+ */
+export function writeOpenCodeHostConfig(cwd, classification) {
+  const path = join(cwd, '.opencode', 'construct-skills.json');
+  const existing = readJsonSafe(path) || {};
+  const currentDisabled = existing?.recommendedDisable || existing?.disabledSkills || [];
+  const disabledSkills = unionArrays(currentDisabled, classification.irrelevant);
+  writeJsonPretty(path, {
+    $comment: 'Construct-owned sidecar. OpenCode rejects unknown top-level opencode.json keys; construct-mcp reads .cx/skills-profile.json at session start.',
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    source: '.cx/skills-profile.json',
+    recommendedDisable: disabledSkills,
+    disabledSkills,
+    protected: classification.protected || [],
+  });
+  return path;
+}
+
+/**
+ * Writes per-project Codex config hints. Codex config is TOML; to avoid a TOML
+ * dependency we write a sidecar JSON file instead — `.codex/skills-profile.json` —
+ * that the Codex adapter can read at session start. Users who want the filter
+ * baked into codex config itself can run `construct sync` after this.
+ */
+export function writeCodexHostConfig(cwd, classification) {
+  const path = join(cwd, '.codex', 'skills-profile.json');
+  writeJsonPretty(path, {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    disabledSkills: classification.irrelevant,
+  });
+  return path;
+}
+
+const HOST_WRITERS = {
+  claude: writeClaudeHostConfig,
+  opencode: writeOpenCodeHostConfig,
+  codex: writeCodexHostConfig,
+};
+
+function parseArgs(args) {
+  const options = { host: null, dryRun: false, cwd: process.cwd(), yes: false };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--dry-run' || arg === '-n') options.dryRun = true;
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--host') options.host = args[++i];
+    else if (arg.startsWith('--host=')) options.host = arg.slice(7);
+    else if (arg === '--cwd') options.cwd = args[++i];
+    else if (arg.startsWith('--cwd=')) options.cwd = arg.slice(6);
+  }
+  return options;
+}
+
+export async function runSkillsApplyCli(args = []) {
+  const options = parseArgs(args);
+
+  if (options.help) {
+    console.log(`Usage: construct skills apply --host <name> [options]
+
+Applies a per-project skill filter based on the detected project profile.
+Writes host-specific config that scopes which skills auto-inject for this
+project, reducing per-turn context bloat without affecting other repos.
+
+Options:
+  --host <name>    claude | opencode | codex | all  (required)
+  --cwd <path>     Target directory (default: CWD)
+  --dry-run, -n    Preview the filter without writing any files
+  --yes, -y        Skip confirmation prompt
+  -h, --help       Show this message
+
+Safety: skills protected by rules/common/doc-ownership.md and Construct's
+cx-* specialist infrastructure are NEVER filtered. The filter is an
+auto-injection scope — disabled skills remain callable via get_skill.
+
+The .cx/skills-profile.json manifest records the decision for audit.
+`);
+    return;
+  }
+
+  if (!options.host) {
+    console.error('Error: --host <claude|opencode|codex|all> is required.');
+    console.error('Run with --help for usage.');
+    process.exit(1);
+  }
+  if (!SUPPORTED_HOSTS.has(options.host)) {
+    console.error(`Error: unknown host "${options.host}". Supported: claude, opencode, codex, all.`);
+    process.exit(1);
+  }
+
+  const cwd = resolve(options.cwd);
+  const profile = detectProjectProfile(cwd);
+
+  if (profile.tags.length === 0) {
+    console.log('No tech-stack signals detected in this directory.');
+    console.log('Skipping filter generation — an empty profile would disable nothing useful.');
+    return;
+  }
+
+  const installed = enumerateInstalledSkills(homedir());
+  const classification = classifySkillRelevance(profile, installed);
+
+  console.log('Project profile');
+  console.log('═══════════════');
+  console.log(`  Detected: ${profile.tags.join(', ')}`);
+  console.log(`  Host:     ${options.host}`);
+  console.log('');
+  console.log(`  Installed skills: ${installed.length}`);
+  console.log(`  Protected:        ${classification.protected.length} (never filtered)`);
+  console.log(`  Relevant:         ${classification.relevant.length}`);
+  console.log(`  Unmapped:         ${classification.unknown.length}`);
+  console.log(`  Will be disabled: ${classification.irrelevant.length}`);
+  console.log('');
+
+  if (classification.irrelevant.length === 0) {
+    console.log('Nothing to disable — exiting.');
+    return;
+  }
+
+  console.log('Skills that will be disabled for this project:');
+  console.log(classification.irrelevant.map((s) => `  - ${s}`).join('\n'));
+  console.log('');
+  console.log('Safeguards applied:');
+  console.log(`  - ${classification.protected.length} skills protected by construct safeguards`);
+  console.log(`  - ${classification.unknown.length} unmapped skills kept as relevant by default`);
+  console.log(`  - Disabled skills remain on disk; callable via get_skill on demand`);
+  console.log(`  - cx-* specialists use construct-mcp get_skill (never host injection)`);
+  console.log('');
+
+  if (options.dryRun) {
+    console.log('Dry run — no files written. Use without --dry-run to apply.');
+    return;
+  }
+
+  // Always write the construct manifest first — it's the authoritative record.
+  const manifestPath = writeConstructManifest(cwd, profile, classification);
+  writeProfile(profile, cwd);
+  console.log(`✓ Manifest: ${manifestPath}`);
+
+  const hostsToWrite = options.host === 'all' ? ['claude', 'opencode', 'codex'] : [options.host];
+  for (const host of hostsToWrite) {
+    const writer = HOST_WRITERS[host];
+    if (!writer) continue;
+    try {
+      const path = writer(cwd, classification);
+      console.log(`✓ ${host.padEnd(8)}: ${path}`);
+    } catch (err) {
+      console.error(`✗ ${host.padEnd(8)}: ${err?.message || 'write failed'}`);
+    }
+  }
+  console.log('');
+  console.log('Manifest + per-host sidecars written. Host support varies:');
+  console.log('  - Claude Code:  sidecar at .claude/construct-skills.json (advisory today;');
+  console.log('                  construct-mcp can read it at session start).');
+  console.log('  - OpenCode:     sidecar at .opencode/construct-skills.json');
+  console.log('                  (construct-owned metadata; avoids invalid opencode.json keys).');
+  console.log('  - Codex:        sidecar at .codex/skills-profile.json (adapter reads at startup).');
+  console.log('');
+  console.log('The authoritative record is .cx/skills-profile.json (version-controllable).');
+  console.log('To revert: delete the files under .claude/, .opencode/, or .codex/ as appropriate.');
+}

package/lib/skills-scope.mjs

@@ -0,0 +1,118 @@
+/**
+ * lib/skills-scope.mjs — CLI surface for project-profile-driven skill scoping.
+ *
+ * Powers `construct skills scope` (and, later, auto-generation of per-host
+ * skill filters). The detection layer is in lib/project-profile.mjs and is
+ * host-agnostic by design — this file composes it into a reportable workflow
+ * and will later wire per-host filter writers.
+ */
+import { homedir } from 'node:os';
+import {
+  classifySkillRelevance,
+  detectProjectProfile,
+  enumerateInstalledSkills,
+  writeProfile,
+} from './project-profile.mjs';
+
+function formatList(list, { limit = 20 } = {}) {
+  if (list.length === 0) return '  (none)';
+  const shown = list.slice(0, limit);
+  const rest = list.length > limit ? `\n  ... and ${list.length - limit} more` : '';
+  return shown.map((name) => `  - ${name}`).join('\n') + rest;
+}
+
+export async function runSkillsScopeCli(args = []) {
+  const flags = new Set();
+  const options = { cwd: process.cwd() };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--json') flags.add('json');
+    else if (arg === '--write') flags.add('write');
+    else if (arg === '--no-write') flags.add('no-write');
+    else if (arg === '--help' || arg === '-h') flags.add('help');
+    else if (arg === '--cwd') options.cwd = args[++i];
+    else if (arg.startsWith('--cwd=')) options.cwd = arg.slice(6);
+  }
+
+  if (flags.has('help')) {
+    console.log(`Usage: construct skills scope [options]
+
+Detects the project's tech stack from filesystem signals (package.json,
+pyproject.toml, go.mod, Cargo.toml, etc.) and reports which installed
+skills are relevant vs irrelevant to the current repo.
+
+Writes .cx/project-profile.json by default (disable with --no-write).
+
+Options:
+  --cwd <path>   Target directory (defaults to CWD)
+  --json         Emit the profile + classification as JSON
+  --no-write     Skip writing .cx/project-profile.json
+  --write        Force write (default behavior)
+  -h, --help     Show this message
+
+The detection layer is host-agnostic. A future pass can use the profile to
+generate per-host skill filters (.claude/ sidecars, .opencode/ sidecars, etc.).
+`);
+    return;
+  }
+
+  const profile = detectProjectProfile(options.cwd);
+  const installed = enumerateInstalledSkills(homedir());
+  const classification = classifySkillRelevance(profile, installed);
+
+  let profilePath = null;
+  if (!flags.has('no-write')) {
+    try { profilePath = writeProfile(profile, options.cwd); } catch { /* best effort */ }
+  }
+
+  if (flags.has('json')) {
+    console.log(JSON.stringify({
+      profile,
+      classification,
+      installedCount: installed.length,
+      profilePath,
+    }, null, 2));
+    return;
+  }
+
+  const irrelevantRatio = installed.length === 0 ? 0 :
+    Math.round((classification.irrelevant.length / installed.length) * 100);
+
+  console.log('Project profile');
+  console.log('═══════════════');
+  console.log(`  Root     ${profile.root}`);
+  console.log(`  Detected ${profile.tags.length ? profile.tags.join(', ') : '(no signals matched)'}`);
+  console.log(`  Signals  ${profile.signals.length ? profile.signals.join(', ') : '(none)'}`);
+  if (profilePath) console.log(`  Saved    ${profilePath}`);
+  console.log('');
+
+  console.log('Installed skills classification');
+  console.log('───────────────────────────────');
+  console.log(`  Total installed: ${installed.length}`);
+  console.log(`  Relevant:        ${classification.relevant.length}`);
+  console.log(`  Irrelevant:      ${classification.irrelevant.length} (${irrelevantRatio}% of total)`);
+  console.log(`  Unmapped:        ${classification.unknown.length} (default: treat as relevant)`);
+  console.log('');
+
+  if (classification.irrelevant.length > 0) {
+    console.log('Irrelevant skills for this project:');
+    console.log(formatList(classification.irrelevant));
+    console.log('');
+    console.log('These are loaded on every turn by the host but do not match this');
+    console.log('project\'s tech stack. To reduce per-turn context footprint:');
+    console.log('');
+    console.log('  - Claude Code: edit ~/.claude/settings.json or per-project .claude/');
+    console.log('    plugins.json to disable plugins you don\'t need in this repo.');
+    console.log('  - OpenCode:    edit ~/.config/opencode/opencode.json');
+    console.log('  - Codex:       edit ~/.codex/agents/ filters');
+    console.log('');
+    console.log('Future: `construct skills apply --host <name>` will generate these');
+    console.log('filter configs automatically from the profile above.');
+  }
+
+  if (classification.unknown.length > 0 && classification.unknown.length < 40) {
+    console.log('');
+    console.log(`Unmapped skills (no relevance rule — default kept):`);
+    console.log(formatList(classification.unknown, { limit: 10 }));
+  }
+}