claude-code-modes 0.1.0

package/src/inspect.ts

@@ -0,0 +1,315 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { parseCliArgs } from "./args.js";
+import { loadConfig, resolveConfigPath, type LoadedConfig } from "./config.js";
+import { resolveConfig } from "./resolve.js";
+import { getFragmentOrder } from "./assemble.js";
+import { detectEnv, buildTemplateVars } from "./env.js";
+import type { TemplateVars } from "./types.js";
+
+const PROVENANCE_VALUES = ["built-in", "config-defined", "cli-path"] as const;
+type Provenance = (typeof PROVENANCE_VALUES)[number];
+
+const WARNING_KINDS = ["outside-project", "non-md", "missing-file", "suspicious-path"] as const;
+type WarningKind = (typeof WARNING_KINDS)[number];
+
+interface FragmentEntry {
+  index: number;
+  path: string;
+  resolvedPath: string;
+  provenance: Provenance;
+}
+
+interface Warning {
+  fragmentIndex: number;
+  fragmentPath: string;
+  kind: WarningKind;
+  detail: string;
+}
+
+interface ConfigSource {
+  loaded: boolean;
+  path: string | null;
+  scope: "project" | "global" | null;
+}
+
+interface InspectResult {
+  baseName: string;
+  configSource: ConfigSource;
+  fragments: FragmentEntry[];
+  fragmentContents: Map<number, string | null>;
+  warnings: Warning[];
+  templateVars: TemplateVars;
+  verbose: boolean;
+}
+
+const SUSPICIOUS_PATTERN = /\.(ssh|env|gnupg|aws|kube|docker|pgpass)|\.npmrc|\.netrc|id_rsa|id_ed25519|id_ecdsa|credentials|secret|token|password|private/i;
+
+/** Builds a Set of all absolute paths that config definitions could resolve to. */
+function collectConfigDefinedPaths(loadedConfig: LoadedConfig | null): Set<string> {
+  const paths = new Set<string>();
+  if (!loadedConfig) return paths;
+
+  const { config, configDir } = loadedConfig;
+
+  // Modifier definitions
+  if (config.modifiers) {
+    for (const val of Object.values(config.modifiers)) {
+      paths.add(resolveConfigPath(configDir, val));
+    }
+  }
+
+  // Axis definitions
+  if (config.axes) {
+    for (const axisName of ["agency", "quality", "scope"] as const) {
+      const axisMap = config.axes[axisName];
+      if (axisMap) {
+        for (const val of Object.values(axisMap)) {
+          paths.add(resolveConfigPath(configDir, val));
+        }
+      }
+    }
+  }
+
+  // Preset modifier lists
+  if (config.presets) {
+    for (const preset of Object.values(config.presets)) {
+      if (preset.modifiers) {
+        for (const mod of preset.modifiers) {
+          // Modifier names resolve through config.modifiers; raw paths resolve against configDir
+          if (config.modifiers && mod in config.modifiers) {
+            paths.add(resolveConfigPath(configDir, config.modifiers[mod]));
+          }
+        }
+      }
+    }
+  }
+
+  // defaultModifiers
+  if (config.defaultModifiers) {
+    for (const mod of config.defaultModifiers) {
+      if (config.modifiers && mod in config.modifiers) {
+        paths.add(resolveConfigPath(configDir, config.modifiers[mod]));
+      }
+    }
+  }
+
+  return paths;
+}
+
+/** Classifies a single fragment path as built-in, config-defined, or cli-path. */
+function classifyProvenance(
+  fragPath: string,
+  configDefinedPaths: Set<string>,
+): Provenance {
+  if (!isAbsolute(fragPath)) return "built-in";
+  if (configDefinedPaths.has(fragPath)) return "config-defined";
+  return "cli-path";
+}
+
+/** Detects warnings for the fragment manifest. */
+function detectWarnings(
+  fragments: FragmentEntry[],
+  promptsDir: string,
+): Warning[] {
+  const warnings: Warning[] = [];
+  const cwd = process.cwd();
+  const resolvedPromptsDir = resolve(promptsDir);
+
+  for (const frag of fragments) {
+    if (frag.provenance === "built-in") {
+      // Only check existence for built-in fragments
+      if (!existsSync(frag.resolvedPath)) {
+        warnings.push({
+          fragmentIndex: frag.index,
+          fragmentPath: frag.path,
+          kind: "missing-file",
+          detail: `file not found: ${frag.resolvedPath}`,
+        });
+      }
+      continue;
+    }
+
+    // Custom fragments: check all warning types
+    // Use cwd + "/" to prevent prefix attacks (e.g. /project-evil matching /project)
+    const inProject = frag.resolvedPath === cwd || frag.resolvedPath.startsWith(cwd + "/");
+    const inPrompts = frag.resolvedPath === resolvedPromptsDir || frag.resolvedPath.startsWith(resolvedPromptsDir + "/");
+    if (!inProject && !inPrompts) {
+      warnings.push({
+        fragmentIndex: frag.index,
+        fragmentPath: frag.resolvedPath,
+        kind: "outside-project",
+        detail: `resolves outside project directory`,
+      });
+    }
+
+    if (!frag.resolvedPath.endsWith(".md")) {
+      warnings.push({
+        fragmentIndex: frag.index,
+        fragmentPath: frag.resolvedPath,
+        kind: "non-md",
+        detail: `non-.md extension`,
+      });
+    }
+
+    if (!existsSync(frag.resolvedPath)) {
+      warnings.push({
+        fragmentIndex: frag.index,
+        fragmentPath: frag.resolvedPath,
+        kind: "missing-file",
+        detail: `file not found`,
+      });
+    }
+
+    if (SUSPICIOUS_PATTERN.test(frag.resolvedPath)) {
+      warnings.push({
+        fragmentIndex: frag.index,
+        fragmentPath: frag.resolvedPath,
+        kind: "suspicious-path",
+        detail: `references potentially sensitive path`,
+      });
+    }
+  }
+
+  return warnings;
+}
+
+/** Determines config source info from LoadedConfig. */
+function describeConfigSource(loadedConfig: LoadedConfig | null): ConfigSource {
+  if (!loadedConfig) return { loaded: false, path: null, scope: null };
+
+  const { configDir } = loadedConfig;
+  const cwd = process.cwd();
+
+  if (configDir === cwd) {
+    return { loaded: true, path: resolve(configDir, ".claude-mode.json"), scope: "project" };
+  }
+  return { loaded: true, path: resolve(configDir, "config.json"), scope: "global" };
+}
+
+/** Formats an InspectResult as a human-readable string. */
+function formatInspectOutput(result: InspectResult): string {
+  const lines: string[] = [];
+
+  // Warning banner — top of output when warnings exist
+  if (result.warnings.length > 0) {
+    const count = result.warnings.length;
+    lines.push(`!! ${count} warning${count > 1 ? "s" : ""} found -- review before running`);
+    lines.push("");
+  }
+
+  // Config section
+  lines.push("=== Config ===");
+  if (!result.configSource.loaded) {
+    lines.push("No config file found.");
+  } else {
+    const label = result.configSource.scope === "project"
+      ? ".claude-mode.json (project)"
+      : "config.json (global)";
+    lines.push(`Loaded: ${label}`);
+    lines.push(`  Path: ${result.configSource.path}`);
+  }
+  lines.push("");
+
+  // Base section
+  lines.push("=== Base ===");
+  lines.push(`Active: ${result.baseName}`);
+  lines.push("");
+
+  // Warnings section — before fragments so issues surface early
+  lines.push("=== Warnings ===");
+  if (result.warnings.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const w of result.warnings) {
+      lines.push(`[!] #${w.fragmentIndex} ${w.detail}: ${w.fragmentPath}`);
+    }
+  }
+  lines.push("");
+
+  // Fragments section
+  lines.push("=== Fragments ===");
+  if (result.verbose) {
+    for (const frag of result.fragments) {
+      const displayPath = frag.provenance === "built-in" ? frag.path : frag.resolvedPath;
+      lines.push("");
+      lines.push(`--- #${frag.index} [${frag.provenance}] ${displayPath} ---`);
+      const content = result.fragmentContents.get(frag.index);
+      if (content === null || content === undefined) {
+        lines.push("(file not found)");
+      } else {
+        lines.push(content.trim());
+      }
+    }
+  } else {
+    const indexWidth = String(result.fragments.length).length;
+    lines.push(`${" ".repeat(indexWidth + 1)} Provenance       Path`);
+    for (const frag of result.fragments) {
+      const idx = String(frag.index).padStart(indexWidth);
+      const prov = frag.provenance.padEnd(16);
+      const displayPath = frag.provenance === "built-in" ? frag.path : frag.resolvedPath;
+      lines.push(`${idx}  ${prov} ${displayPath}`);
+    }
+  }
+  lines.push("");
+
+  // Template variables section
+  lines.push("=== Template Variables ===");
+  const maxKeyLen = Math.max(...Object.keys(result.templateVars).map((k) => k.length));
+  for (const [key, value] of Object.entries(result.templateVars)) {
+    const displayValue = value.includes("\n") ? "(multiline)" : value;
+    lines.push(`${key.padEnd(maxKeyLen)} = ${displayValue}`);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/** Reads a fragment file, returning its content or null if missing. */
+function readFragmentContent(resolvedPath: string): string | null {
+  try {
+    return readFileSync(resolvedPath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Runs the inspect subcommand. Accepts argv after "inspect" has been stripped. */
+export function runInspectCommand(argv: string[], promptsDir: string): void {
+  const verbose = argv.includes("--print");
+  const filteredArgv = argv.filter((a) => a !== "--print");
+
+  const parsed = parseCliArgs(filteredArgv);
+  const loadedConfig = loadConfig();
+  const config = resolveConfig(parsed, loadedConfig);
+
+  const env = detectEnv();
+  const templateVars = buildTemplateVars(env);
+
+  const fragmentPaths = getFragmentOrder(config, promptsDir);
+  const configDefinedPaths = collectConfigDefinedPaths(loadedConfig);
+
+  const fragments: FragmentEntry[] = fragmentPaths.map((fragPath, i) => {
+    const resolvedPath = isAbsolute(fragPath)
+      ? fragPath
+      : resolve(promptsDir, fragPath);
+    return {
+      index: i + 1,
+      path: fragPath,
+      resolvedPath,
+      provenance: classifyProvenance(fragPath, configDefinedPaths),
+    };
+  });
+
+  const fragmentContents = new Map<number, string | null>();
+  if (verbose) {
+    for (const frag of fragments) {
+      fragmentContents.set(frag.index, readFragmentContent(frag.resolvedPath));
+    }
+  }
+
+  const warnings = detectWarnings(fragments, promptsDir);
+  const configSource = describeConfigSource(loadedConfig);
+
+  const result: InspectResult = { baseName: config.base, configSource, fragments, fragmentContents, warnings, templateVars, verbose };
+  process.stdout.write(formatInspectOutput(result));
+}

package/src/presets.ts

@@ -0,0 +1,39 @@
+import type { AxisConfig, PresetName } from "./types.js";
+export { isPresetName } from "./types.js";
+
+export interface PresetDefinition {
+  axes: AxisConfig | null;
+  readonly: boolean;
+}
+
+const PRESETS: Record<PresetName, PresetDefinition> = {
+  "create": {
+    axes: { agency: "autonomous", quality: "architect", scope: "unrestricted" },
+    readonly: false,
+  },
+  "extend": {
+    axes: { agency: "autonomous", quality: "pragmatic", scope: "adjacent" },
+    readonly: false,
+  },
+  "safe": {
+    axes: { agency: "collaborative", quality: "minimal", scope: "narrow" },
+    readonly: false,
+  },
+  "refactor": {
+    axes: { agency: "autonomous", quality: "pragmatic", scope: "unrestricted" },
+    readonly: false,
+  },
+  "explore": {
+    axes: { agency: "collaborative", quality: "architect", scope: "narrow" },
+    readonly: true,
+  },
+  "none": {
+    axes: null,
+    readonly: false,
+  },
+};
+
+export function getPreset(name: PresetName): PresetDefinition {
+  return PRESETS[name];
+}
+

package/src/resolve.ts

@@ -0,0 +1,278 @@
+import type { ModeConfig } from "./types.js";
+import type { ParsedArgs } from "./args.js";
+import type { LoadedConfig } from "./config.js";
+import { resolveConfigPath } from "./config.js";
+import { getPreset, isPresetName } from "./presets.js";
+import {
+  AGENCY_VALUES,
+  QUALITY_VALUES,
+  SCOPE_VALUES,
+  BUILTIN_MODIFIER_NAMES,
+  BUILTIN_BASE_NAMES,
+  PRESET_NAMES,
+  isBuiltinModifier,
+  isBuiltinBase,
+} from "./types.js";
+import { resolve as pathResolve, isAbsolute } from "node:path";
+
+const DEFAULT_AGENCY = "collaborative";
+const DEFAULT_QUALITY = "pragmatic";
+const DEFAULT_SCOPE = "adjacent";
+
+/**
+ * Returns true if a string looks like a file path rather than a name.
+ * Paths contain "/" or "\" or end with ".md".
+ */
+function looksLikeFilePath(value: string): boolean {
+  return value.includes("/") || value.includes("\\") || value.endsWith(".md");
+}
+
+/**
+ * Resolves an axis value to either a built-in name or an absolute path.
+ * Resolution order: built-in values → config-defined names → file path heuristic.
+ * Throws with descriptive error if unresolvable.
+ */
+function resolveAxisValue(
+  raw: string,
+  axisName: "agency" | "quality" | "scope",
+  builtinValues: readonly string[],
+  loadedConfig: LoadedConfig | null,
+): string {
+  // 1. Built-in value
+  if (builtinValues.includes(raw)) return raw;
+
+  // 2. Config-defined custom name
+  const configAxes = loadedConfig?.config.axes?.[axisName];
+  if (configAxes && raw in configAxes) {
+    return resolveConfigPath(loadedConfig!.configDir, configAxes[raw]);
+  }
+
+  // 3. File path
+  if (looksLikeFilePath(raw)) {
+    return isAbsolute(raw) ? raw : pathResolve(raw);
+  }
+
+  // 4. Unknown
+  const configHint = loadedConfig
+    ? ` Config loaded from: ${loadedConfig.configDir}`
+    : " No config file found.";
+  throw new Error(
+    `Unknown --${axisName} value: "${raw}". ` +
+    `Must be one of: ${builtinValues.join(", ")}, ` +
+    `a name defined in your config, or a file path.${configHint}`
+  );
+}
+
+/**
+ * Resolves a modifier reference to either a built-in flag name or an absolute path.
+ * Resolution order: built-in modifier name → config-defined name → file path.
+ */
+function resolveModifier(
+  raw: string,
+  loadedConfig: LoadedConfig | null,
+): { kind: "builtin"; name: string } | { kind: "custom"; path: string } {
+  // 1. Built-in modifier
+  if (isBuiltinModifier(raw)) {
+    return { kind: "builtin", name: raw };
+  }
+
+  // 2. Config-defined custom modifier
+  const configModifiers = loadedConfig?.config.modifiers;
+  if (configModifiers && raw in configModifiers) {
+    return {
+      kind: "custom",
+      path: resolveConfigPath(loadedConfig!.configDir, configModifiers[raw]),
+    };
+  }
+
+  // 3. File path
+  if (looksLikeFilePath(raw)) {
+    const absPath = isAbsolute(raw) ? raw : pathResolve(raw);
+    return { kind: "custom", path: absPath };
+  }
+
+  // 4. Unknown
+  const configHint = loadedConfig
+    ? ` Config loaded from: ${loadedConfig.configDir}`
+    : " No config file found.";
+  throw new Error(
+    `Unknown modifier: "${raw}". ` +
+    `Must be a built-in modifier (${BUILTIN_MODIFIER_NAMES.join(", ")}), ` +
+    `a name defined in your config, or a file path.${configHint}`
+  );
+}
+
+/** Resolves a list of modifier references, updating flags and custom paths in place. */
+function applyModifiers(
+  modifiers: string[],
+  loadedConfig: LoadedConfig | null,
+  flags: { readonly: boolean; contextPacing: boolean },
+  customPaths: string[],
+  position: "append" | "prepend",
+): void {
+  for (const raw of modifiers) {
+    const resolved = resolveModifier(raw, loadedConfig);
+    if (resolved.kind === "builtin") {
+      if (resolved.name === "readonly") flags.readonly = true;
+      if (resolved.name === "context-pacing") flags.contextPacing = true;
+    } else {
+      if (!customPaths.includes(resolved.path)) {
+        if (position === "prepend") customPaths.unshift(resolved.path);
+        else customPaths.push(resolved.path);
+      }
+    }
+  }
+}
+
+/**
+ * Resolves a base reference to a built-in name or absolute directory path.
+ * Priority: CLI --base > preset base > config defaultBase > "standard"
+ */
+function resolveBase(
+  raw: string | undefined,
+  loadedConfig: LoadedConfig | null,
+  presetBase: string | undefined,
+): string {
+  const config = loadedConfig?.config ?? null;
+
+  // Priority: CLI --base > preset base > config defaultBase > "standard"
+  const value = raw ?? presetBase ?? config?.defaultBase ?? "standard";
+
+  // 1. Built-in name
+  if (isBuiltinBase(value)) return value;
+
+  // 2. Config-defined name
+  const configBases = config?.bases;
+  if (configBases && value in configBases) {
+    return resolveConfigPath(loadedConfig!.configDir, configBases[value]);
+  }
+
+  // 3. Directory path
+  if (looksLikeFilePath(value)) {
+    return isAbsolute(value) ? value : pathResolve(value);
+  }
+
+  // 4. Unknown
+  const configHint = loadedConfig
+    ? ` Config loaded from: ${loadedConfig.configDir}`
+    : " No config file found.";
+  throw new Error(
+    `Unknown --base value: "${value}". ` +
+    `Must be one of: ${BUILTIN_BASE_NAMES.join(", ")}, ` +
+    `a name defined in your config, or a directory path.${configHint}`
+  );
+}
+
+export function resolveConfig(
+  parsed: ParsedArgs,
+  loadedConfig: LoadedConfig | null,
+): ModeConfig {
+  const config = loadedConfig?.config ?? null;
+
+  // Resolve modifiers: defaultModifiers (config) → --modifier flags (CLI)
+  const flags = { readonly: parsed.modifiers.readonly, contextPacing: parsed.modifiers.contextPacing };
+  const customModifierPaths: string[] = [];
+
+  // 1. Config defaultModifiers — always applied first
+  if (config?.defaultModifiers) {
+    applyModifiers(config.defaultModifiers, loadedConfig, flags, customModifierPaths, "append");
+  }
+
+  // 2. CLI --modifier flags — appended after defaults
+  applyModifiers(parsed.customModifiers, loadedConfig, flags, customModifierPaths, "append");
+
+  // Handle "none" preset — resolve base before early return
+  if (parsed.preset === "none") {
+    const base = resolveBase(parsed.base, loadedConfig, undefined);
+    return {
+      base,
+      axes: null,
+      modifiers: {
+        readonly: flags.readonly,
+        contextPacing: flags.contextPacing,
+        custom: customModifierPaths,
+      },
+    };
+  }
+
+  let agency: string;
+  let quality: string;
+  let scope: string;
+  let presetBase: string | undefined;
+
+  if (parsed.preset) {
+    // Check built-in presets first, then config presets
+    if (isPresetName(parsed.preset)) {
+      const preset = getPreset(parsed.preset);
+      if (preset.axes === null) throw new Error(`Preset "${parsed.preset}" has null axes`);
+      agency = parsed.overrides.agency
+        ? resolveAxisValue(parsed.overrides.agency, "agency", AGENCY_VALUES, loadedConfig)
+        : preset.axes.agency;
+      quality = parsed.overrides.quality
+        ? resolveAxisValue(parsed.overrides.quality, "quality", QUALITY_VALUES, loadedConfig)
+        : preset.axes.quality;
+      scope = parsed.overrides.scope
+        ? resolveAxisValue(parsed.overrides.scope, "scope", SCOPE_VALUES, loadedConfig)
+        : preset.axes.scope;
+      flags.readonly = flags.readonly || preset.readonly;
+      // Built-in presets don't specify a base — presetBase stays undefined
+    } else if (config?.presets && parsed.preset in config.presets) {
+      // Config-defined preset
+      const customPreset = config.presets[parsed.preset];
+      presetBase = customPreset.base;
+      agency = parsed.overrides.agency
+        ? resolveAxisValue(parsed.overrides.agency, "agency", AGENCY_VALUES, loadedConfig)
+        : customPreset.agency
+          ? resolveAxisValue(customPreset.agency, "agency", AGENCY_VALUES, loadedConfig)
+          : DEFAULT_AGENCY;
+      quality = parsed.overrides.quality
+        ? resolveAxisValue(parsed.overrides.quality, "quality", QUALITY_VALUES, loadedConfig)
+        : customPreset.quality
+          ? resolveAxisValue(customPreset.quality, "quality", QUALITY_VALUES, loadedConfig)
+          : DEFAULT_QUALITY;
+      scope = parsed.overrides.scope
+        ? resolveAxisValue(parsed.overrides.scope, "scope", SCOPE_VALUES, loadedConfig)
+        : customPreset.scope
+          ? resolveAxisValue(customPreset.scope, "scope", SCOPE_VALUES, loadedConfig)
+          : DEFAULT_SCOPE;
+      if (customPreset.readonly) flags.readonly = true;
+      if (customPreset.contextPacing) flags.contextPacing = true;
+
+      // Resolve preset's modifiers list — inserted before CLI modifiers
+      if (customPreset.modifiers) {
+        applyModifiers(customPreset.modifiers, loadedConfig, flags, customModifierPaths, "prepend");
+      }
+    } else {
+      throw new Error(
+        `Unknown preset: "${parsed.preset}". ` +
+        `Built-in presets: ${PRESET_NAMES.join(", ")}. ` +
+        (config?.presets
+          ? `Config presets: ${Object.keys(config.presets).join(", ")}.`
+          : "No config file found.")
+      );
+    }
+  } else {
+    // No preset: use overrides with defaults
+    agency = parsed.overrides.agency
+      ? resolveAxisValue(parsed.overrides.agency, "agency", AGENCY_VALUES, loadedConfig)
+      : DEFAULT_AGENCY;
+    quality = parsed.overrides.quality
+      ? resolveAxisValue(parsed.overrides.quality, "quality", QUALITY_VALUES, loadedConfig)
+      : DEFAULT_QUALITY;
+    scope = parsed.overrides.scope
+      ? resolveAxisValue(parsed.overrides.scope, "scope", SCOPE_VALUES, loadedConfig)
+      : DEFAULT_SCOPE;
+  }
+
+  const base = resolveBase(parsed.base, loadedConfig, presetBase);
+
+  return {
+    base,
+    axes: { agency, quality, scope },
+    modifiers: {
+      readonly: flags.readonly,
+      contextPacing: flags.contextPacing,
+      custom: customModifierPaths,
+    },
+  };
+}