gsdd-cli 0.1.0

package/bin/lib/manifest.mjs

@@ -0,0 +1,134 @@
+// manifest.mjs — Generation manifest for template versioning
+
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+
+const MANIFEST_FILENAME = 'generation-manifest.json';
+
+/**
+ * SHA-256 hex digest of file contents.
+ */
+export function fileHash(filePath) {
+  const content = readFileSync(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Recursive { relativePath: sha256 } map for a directory.
+ * Normalizes backslashes to forward slashes for cross-platform consistency.
+ */
+export function hashDirectory(dir, baseDir = dir) {
+  const result = {};
+  if (!existsSync(dir)) return result;
+
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      Object.assign(result, hashDirectory(fullPath, baseDir));
+    } else {
+      const rel = relative(baseDir, fullPath).replace(/\\/g, '/');
+      result[rel] = fileHash(fullPath);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a full manifest snapshot from installed project files.
+ */
+export function buildManifest({ planningDir, frameworkVersion }) {
+  const templatesDir = join(planningDir, 'templates');
+  const rolesDir = join(templatesDir, 'roles');
+
+  // Template subcategories
+  const delegatesHashes = hashDirectory(join(templatesDir, 'delegates'), join(templatesDir, 'delegates'));
+  const researchHashes = hashDirectory(join(templatesDir, 'research'), join(templatesDir, 'research'));
+  const codebaseHashes = hashDirectory(join(templatesDir, 'codebase'), join(templatesDir, 'codebase'));
+
+  // Root-level template .md files (agents.block.md, spec.md, roadmap.md, etc.)
+  const rootHashes = {};
+  if (existsSync(templatesDir)) {
+    for (const entry of readdirSync(templatesDir)) {
+      const fullPath = join(templatesDir, entry);
+      if (statSync(fullPath).isFile() && entry.endsWith('.md')) {
+        rootHashes[entry] = fileHash(fullPath);
+      }
+    }
+  }
+
+  // Role contracts
+  const rolesHashes = {};
+  if (existsSync(rolesDir)) {
+    for (const entry of readdirSync(rolesDir)) {
+      if (entry.endsWith('.md')) {
+        rolesHashes[entry] = fileHash(join(rolesDir, entry));
+      }
+    }
+  }
+
+  return {
+    frameworkVersion,
+    generatedAt: new Date().toISOString(),
+    templates: {
+      delegates: delegatesHashes,
+      research: researchHashes,
+      codebase: codebaseHashes,
+      root: rootHashes,
+    },
+    roles: rolesHashes,
+  };
+}
+
+/**
+ * Read existing manifest from planningDir, or return null if missing/corrupt.
+ */
+export function readManifest(planningDir) {
+  const manifestPath = join(planningDir, MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write generation-manifest.json to planningDir.
+ */
+export function writeManifest(planningDir, manifest) {
+  const manifestPath = join(planningDir, MANIFEST_FILENAME);
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Compare installed files vs manifest hashes.
+ * Returns { modified: string[], unchanged: string[], missing: string[] }
+ * where each string is a relative filename.
+ */
+export function detectModifications(installedDir, manifestHashes) {
+  const modified = [];
+  const unchanged = [];
+  const missing = [];
+
+  if (!manifestHashes) return { modified, unchanged, missing };
+
+  for (const [file, expectedHash] of Object.entries(manifestHashes)) {
+    const fullPath = join(installedDir, file);
+    if (!existsSync(fullPath)) {
+      missing.push(file);
+      continue;
+    }
+    const currentHash = fileHash(fullPath);
+    if (currentHash === expectedHash) {
+      unchanged.push(file);
+    } else {
+      modified.push(file);
+    }
+  }
+
+  return { modified, unchanged, missing };
+}

package/bin/lib/models.mjs

@@ -0,0 +1,379 @@
+// models.mjs — Model profile management, config CRUD, and validation constants
+//
+// IMPORTANT: No module-scope process.cwd() — ESM caching means sub-modules
+// evaluate once, so CWD must be computed inside function bodies.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { CLAUDE_MODEL_PROFILES } from '../adapters/claude.mjs';
+import { detectOpenCodeConfiguredModel } from '../adapters/opencode.mjs';
+import { parseFlagValue, output } from './cli-utils.mjs';
+
+export const DEFAULT_GIT_PROTOCOL = {
+  branch: 'Follow the existing repo or team branching convention. Use a feature branch for significant changes when no convention exists.',
+  commit: 'Group changes logically and follow the existing repo conventions. Do not mention phase, plan, or task IDs unless explicitly requested.',
+  pr: 'Follow the existing repo or team review workflow. Do not assume PR creation, timing, or naming unless explicitly requested.',
+};
+
+export const VALID_MODEL_PROFILES = ['quality', 'balanced', 'budget'];
+export const PORTABLE_AGENT_IDS = ['plan-checker'];
+export const MODEL_RUNTIME_IDS = ['claude', 'opencode', 'codex'];
+export const MODEL_ID_PATTERN = /^[a-zA-Z0-9._\/:@-]+$/;
+
+export function normalizeModelProfile(value) {
+  return VALID_MODEL_PROFILES.includes(value) ? value : 'balanced';
+}
+
+export function buildDefaultConfig({ autoAdvance = false } = {}) {
+  const config = {
+    researchDepth: 'balanced',
+    parallelization: true,
+    commitDocs: true,
+    modelProfile: 'balanced',
+    workflow: { research: true, planCheck: true, verifier: true },
+    gitProtocol: { ...DEFAULT_GIT_PROTOCOL },
+    initVersion: 'v1.1',
+  };
+  if (autoAdvance) config.autoAdvance = true;
+  return config;
+}
+
+export function isProjectInitialized(cwd = process.cwd()) {
+  return existsSync(join(cwd, '.planning', 'config.json'));
+}
+
+export function loadProjectModelConfig(cwd = process.cwd()) {
+  const configPath = join(cwd, '.planning', 'config.json');
+  if (!existsSync(configPath)) return buildDefaultConfig();
+
+  try {
+    return {
+      ...buildDefaultConfig(),
+      ...JSON.parse(readFileSync(configPath, 'utf-8')),
+    };
+  } catch (e) {
+    console.error(`WARNING: .planning/config.json is malformed (${e.message}). Using defaults.`);
+    return buildDefaultConfig();
+  }
+}
+
+function loadConfigForMutation(cwd = process.cwd()) {
+  const configPath = join(cwd, '.planning', 'config.json');
+  let raw;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch (e) {
+    return { ok: false, error: `could not read config file (${e.message})` };
+  }
+  try {
+    return { ok: true, config: { ...buildDefaultConfig(), ...JSON.parse(raw) } };
+  } catch (e) {
+    return { ok: false, error: `malformed JSON (${e.message})` };
+  }
+}
+
+export function ensureProjectConfig(cwd = process.cwd()) {
+  mkdirSync(join(cwd, '.planning'), { recursive: true });
+  const config = loadProjectModelConfig(cwd);
+  writeProjectConfig(config, cwd);
+  return config;
+}
+
+export function writeProjectConfig(config, cwd = process.cwd()) {
+  const configPath = join(cwd, '.planning', 'config.json');
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+export function getPortableAgentProfile(config, agentId) {
+  const override = config.agentModelProfiles?.[agentId];
+  if (VALID_MODEL_PROFILES.includes(override)) return override;
+  return normalizeModelProfile(config.modelProfile);
+}
+
+export function getRuntimeModelOverride(config, runtime, agentId) {
+  const override = config.runtimeModelOverrides?.[runtime]?.[agentId];
+  return typeof override === 'string' && override.trim() ? override.trim() : null;
+}
+
+export function resolveRuntimeAgentModel({ cwd = process.cwd(), runtime, agentId, profileMap = null }) {
+  const config = loadProjectModelConfig(cwd);
+  const runtimeOverride = getRuntimeModelOverride(config, runtime, agentId);
+  if (runtimeOverride) return runtimeOverride;
+
+  if (!profileMap) return null;
+  const profile = getPortableAgentProfile(config, agentId);
+  return profileMap[profile] ?? profileMap.balanced ?? null;
+}
+
+export function getRuntimeAgentModelState({ config, runtime, agentId, profileMap = null }) {
+  const runtimeOverride = getRuntimeModelOverride(config, runtime, agentId);
+  if (runtimeOverride) {
+    return {
+      mode: 'override',
+      model: runtimeOverride,
+      source: 'runtimeOverride',
+    };
+  }
+
+  if (!profileMap) {
+    return {
+      mode: 'inherit',
+      model: null,
+      runtimeDetectedModel: null,
+    };
+  }
+
+  const agentOverride = config.agentModelProfiles?.[agentId];
+  const profile = getPortableAgentProfile(config, agentId);
+  return {
+    mode: 'mapped',
+    model: profileMap[profile] ?? profileMap.balanced ?? null,
+    source: VALID_MODEL_PROFILES.includes(agentOverride) ? 'agentModelProfile' : 'modelProfile',
+  };
+}
+
+export function cmdModels(...modelArgs) {
+  const subcommand = modelArgs[0] || 'show';
+
+  switch (subcommand) {
+    case 'show':
+      return cmdModelsShow();
+    case 'profile':
+      return cmdModelsProfile(modelArgs[1]);
+    case 'agent-profile':
+      return cmdModelsAgentProfile(modelArgs.slice(1));
+    case 'clear-agent-profile':
+      return cmdModelsClearAgentProfile(modelArgs.slice(1));
+    case 'set':
+      return cmdModelsSetRuntimeOverride(modelArgs.slice(1));
+    case 'clear':
+      return cmdModelsClearRuntimeOverride(modelArgs.slice(1));
+    default:
+      console.error('Usage: gsdd models [show|profile|agent-profile|clear-agent-profile|set|clear]');
+      process.exitCode = 1;
+  }
+}
+
+function cmdModelsShow() {
+  const cwd = process.cwd();
+  const config = loadProjectModelConfig(cwd);
+  const ocOverride = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+  const ocDetected = detectOpenCodeConfiguredModel(cwd);
+  const codexOverride = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+  output({
+    modelProfile: normalizeModelProfile(config.modelProfile),
+    agentModelProfiles: config.agentModelProfiles || {},
+    runtimeModelOverrides: config.runtimeModelOverrides || {},
+    effective: {
+      claude: {
+        'plan-checker': getRuntimeAgentModelState({
+          config,
+          runtime: 'claude',
+          agentId: 'plan-checker',
+          profileMap: CLAUDE_MODEL_PROFILES,
+        }),
+      },
+      opencode: {
+        'plan-checker': {
+          mode: ocOverride ? 'override' : 'inherit',
+          model: ocOverride,
+          runtimeDetectedModel: ocDetected,
+        },
+      },
+      codex: {
+        'plan-checker': {
+          mode: codexOverride ? 'override' : 'inherit',
+          model: codexOverride,
+        },
+      },
+    },
+    detectedRuntimeModels: {
+      opencode: ocDetected,
+    },
+    hints: !ocOverride ? {
+      opencode: 'OpenCode currently inherits its runtime model unless you set an explicit override. Use gsdd models set --runtime opencode --agent plan-checker --model <provider/model-id> to inject an explicit checker model.',
+    } : undefined,
+  });
+}
+
+function cmdModelsProfile(profile) {
+  if (!VALID_MODEL_PROFILES.includes(profile)) {
+    console.error(`ERROR: Invalid profile "${profile}". Valid profiles: ${VALID_MODEL_PROFILES.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running model mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  result.config.modelProfile = profile;
+  writeProjectConfig(result.config);
+  console.log(`  - set modelProfile to ${profile}`);
+  console.log('  Run gsdd update to regenerate adapter files.');
+}
+
+function cmdModelsAgentProfile(args) {
+  const agent = parseFlagValue(args, '--agent').value;
+  const profile = parseFlagValue(args, '--profile').value;
+
+  if (!PORTABLE_AGENT_IDS.includes(agent)) {
+    console.error(`ERROR: Invalid agent "${agent}". Valid agents: ${PORTABLE_AGENT_IDS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!VALID_MODEL_PROFILES.includes(profile)) {
+    console.error(`ERROR: Invalid profile "${profile}". Valid profiles: ${VALID_MODEL_PROFILES.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running model mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  result.config.agentModelProfiles = result.config.agentModelProfiles || {};
+  result.config.agentModelProfiles[agent] = profile;
+  writeProjectConfig(result.config);
+  console.log(`  - set ${agent} semantic profile to ${profile}`);
+  console.log('  Run gsdd update to regenerate adapter files.');
+}
+
+function cmdModelsClearAgentProfile(args) {
+  const agent = parseFlagValue(args, '--agent').value;
+  if (!PORTABLE_AGENT_IDS.includes(agent)) {
+    console.error(`ERROR: Invalid agent "${agent}". Valid agents: ${PORTABLE_AGENT_IDS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running model mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.config.agentModelProfiles) {
+    delete result.config.agentModelProfiles[agent];
+    if (Object.keys(result.config.agentModelProfiles).length === 0) {
+      delete result.config.agentModelProfiles;
+    }
+  }
+  writeProjectConfig(result.config);
+  console.log(`  - cleared semantic profile override for ${agent}`);
+  console.log('  Run gsdd update to regenerate adapter files.');
+}
+
+function cmdModelsSetRuntimeOverride(args) {
+  const runtime = parseFlagValue(args, '--runtime').value;
+  const agent = parseFlagValue(args, '--agent').value;
+  const model = parseFlagValue(args, '--model').value;
+
+  if (!MODEL_RUNTIME_IDS.includes(runtime)) {
+    console.error(`ERROR: Invalid runtime "${runtime}". Valid runtimes: ${MODEL_RUNTIME_IDS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!PORTABLE_AGENT_IDS.includes(agent)) {
+    console.error(`ERROR: Invalid agent "${agent}". Valid agents: ${PORTABLE_AGENT_IDS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!model) {
+    console.error('ERROR: --model requires a value.');
+    process.exitCode = 1;
+    return;
+  }
+  if (!MODEL_ID_PATTERN.test(model.trim())) {
+    console.error('ERROR: Model ID contains invalid characters. Only alphanumeric, dots, hyphens, underscores, forward slashes, colons, and @ are allowed.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running model mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  result.config.runtimeModelOverrides = result.config.runtimeModelOverrides || {};
+  result.config.runtimeModelOverrides[runtime] = result.config.runtimeModelOverrides[runtime] || {};
+  result.config.runtimeModelOverrides[runtime][agent] = model.trim();
+  writeProjectConfig(result.config);
+  console.log(`  - set ${runtime} runtime override for ${agent}`);
+  console.log('  Run gsdd update to regenerate adapter files.');
+}
+
+function cmdModelsClearRuntimeOverride(args) {
+  const runtime = parseFlagValue(args, '--runtime').value;
+  const agent = parseFlagValue(args, '--agent').value;
+
+  if (!MODEL_RUNTIME_IDS.includes(runtime)) {
+    console.error(`ERROR: Invalid runtime "${runtime}". Valid runtimes: ${MODEL_RUNTIME_IDS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!PORTABLE_AGENT_IDS.includes(agent)) {
+    console.error(`ERROR: Invalid agent "${agent}". Valid agents: ${PORTABLE_AGENT_IDS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running model mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.config.runtimeModelOverrides?.[runtime]) {
+    delete result.config.runtimeModelOverrides[runtime][agent];
+    if (Object.keys(result.config.runtimeModelOverrides[runtime]).length === 0) {
+      delete result.config.runtimeModelOverrides[runtime];
+    }
+    if (Object.keys(result.config.runtimeModelOverrides).length === 0) {
+      delete result.config.runtimeModelOverrides;
+    }
+  }
+  writeProjectConfig(result.config);
+  console.log(`  - cleared ${runtime} runtime override for ${agent}`);
+  console.log('  Run gsdd update to regenerate adapter files.');
+}