@entelligentsia/forgecli 0.8.4 → 0.9.1

package/dist/forge-payload/.tools/generation-manifest.cjs

@@ -1,311 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-// Forge tool: generation-manifest
-// Track and verify generated file integrity via content hashes.
-// Usage: generation-manifest record <path>
-//        generation-manifest record-all
-//        generation-manifest check <path>
-//        generation-manifest list [--modified]
-//        generation-manifest status
-//        generation-manifest remove <path>
-//        generation-manifest clear-namespace <prefix>  Remove all entries whose path starts with <prefix>.
-//                                                       prefix must start with .forge/ or .claude/ and end with /
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const MANIFEST_PATH = path.join(process.cwd(), '.forge', 'generation-manifest.json');
-
-function normalize(content) {
-  return content
-    .replace(/\r\n/g, '\n')
-    .split('\n')
-    .map(line => line.trimEnd())
-    .join('\n');
-}
-
-function hashContent(content) {
-  return 'sha256:' + crypto.createHash('sha256').update(normalize(content), 'utf8').digest('hex');
-}
-
-// ── exports (for testing) ────────────────────────────────────────────────────
-
-module.exports = { normalize, hashContent, MANIFEST_PATH };
-
-// ── CLI guard ────────────────────────────────────────────────────────────────
-
-if (require.main === module) {
-process.on('uncaughtException', (e) => {
-  process.stderr.write(`× ${e.message}\n`);
-  process.exit(1);
-});
-
-function readManifest() {
-  if (!fs.existsSync(MANIFEST_PATH)) return { files: {} };
-  try {
-    return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
-  } catch (e) {
-    process.stderr.write(`× reading manifest: ${e.message}\n`);
-    process.exit(1);
-  }
-}
-
-function writeManifest(manifest) {
-  const dir = path.dirname(MANIFEST_PATH);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  const tmp = MANIFEST_PATH + '.tmp.' + process.pid;
-  try {
-    fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, MANIFEST_PATH);
-  } catch (e) {
-    try { fs.unlinkSync(tmp); } catch {}
-    process.stderr.write(`× writing manifest: ${e.message}\n`);
-    process.exit(1);
-  }
-}
-
-function getForgeVersion() {
-  try {
-    const configPath = path.join(process.cwd(), '.forge', 'config.json');
-    if (fs.existsSync(configPath)) {
-      const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-      if (cfg.version) return cfg.version;
-    }
-  } catch {}
-  return 'unknown';
-}
-
-function toRelPath(filePath) {
-  return path.relative(process.cwd(), path.resolve(filePath));
-}
-
-function fileStatus(relPath, entry) {
-  const absPath = path.resolve(relPath);
-  if (!fs.existsSync(absPath)) return 'missing';
-  const current = hashContent(fs.readFileSync(absPath, 'utf8'));
-  return current === entry.hash ? 'pristine' : 'modified';
-}
-
-const STATUS_SYMBOL = { pristine: '〇', modified: '△', missing: '×' };
-
-// ── subcommands ──────────────────────────────────────────────────────────────
-
-const [,, subcmd, ...args] = process.argv;
-
-if (!subcmd) {
-  process.stderr.write([
-    'Usage: generation-manifest <subcommand> [options]',
-    '',
-    'Subcommands:',
-    '  record <path>        Hash and store/update a file in the manifest',
-    '  record-all           Re-hash all files currently tracked in the manifest',
-    '  check <path>         Exit 0=pristine  1=modified  2=untracked  3=file missing',
-    '  list [--modified]    Table of tracked files with status',
-    '  status               Summary counts',
-    '  remove <path>        Remove a file from tracking',
-    '  clear-namespace <prefix>  Remove all entries whose path starts with <prefix>.',
-    '                            prefix must start with .forge/ or .claude/ and end with /',
-  ].join('\n') + '\n');
-  process.exit(2);
-}
-
-// ── record ───────────────────────────────────────────────────────────────────
-
-if (subcmd === 'record') {
-  const filePath = args[0];
-  if (!filePath) {
-    process.stderr.write('Usage: generation-manifest record <path>\n');
-    process.exit(2);
-  }
-  const relPath = toRelPath(filePath);
-  const absPath = path.resolve(filePath);
-  if (!fs.existsSync(absPath)) {
-    process.stderr.write(`× File not found: ${filePath}\n`);
-    process.exit(1);
-  }
-  const manifest = readManifest();
-  if (!manifest.files) manifest.files = {};
-  manifest.files[relPath] = {
-    hash: hashContent(fs.readFileSync(absPath, 'utf8')),
-    generatedAt: new Date().toISOString(),
-    generatedByVersion: getForgeVersion(),
-  };
-  writeManifest(manifest);
-  process.stdout.write(`〇 Recorded: ${relPath}\n`);
-  process.exit(0);
-}
-
-// ── record-all ───────────────────────────────────────────────────────────────
-
-if (subcmd === 'record-all') {
-  const manifest = readManifest();
-  const files = manifest.files || {};
-  if (Object.keys(files).length === 0) {
-    process.stdout.write('── No files tracked — nothing to re-hash.\n');
-    process.exit(0);
-  }
-  let updated = 0, missing = 0;
-  const version = getForgeVersion();
-  for (const relPath of Object.keys(files)) {
-    const absPath = path.resolve(relPath);
-    if (!fs.existsSync(absPath)) {
-      process.stdout.write(`△ Missing (skipped): ${relPath}\n`);
-      missing++;
-      continue;
-    }
-    files[relPath] = {
-      hash: hashContent(fs.readFileSync(absPath, 'utf8')),
-      generatedAt: new Date().toISOString(),
-      generatedByVersion: version,
-    };
-    updated++;
-  }
-  writeManifest(manifest);
-  process.stdout.write(`〇 Re-hashed ${updated} file(s).${missing ? `  △ ${missing} missing.` : ''}\n`);
-  process.exit(0);
-}
-
-// ── check ────────────────────────────────────────────────────────────────────
-
-if (subcmd === 'check') {
-  const filePath = args[0];
-  if (!filePath) {
-    process.stderr.write('Usage: generation-manifest check <path>\n');
-    process.exit(2);
-  }
-  const relPath = toRelPath(filePath);
-  const manifest = readManifest();
-  const entry = manifest.files && manifest.files[relPath];
-
-  if (!entry) {
-    process.stdout.write(`── ${relPath}: untracked\n`);
-    process.exit(2);
-  }
-  const absPath = path.resolve(relPath);
-  if (!fs.existsSync(absPath)) {
-    process.stdout.write(`× ${relPath}: file not found\n`);
-    process.exit(3);
-  }
-  const current = hashContent(fs.readFileSync(absPath, 'utf8'));
-  if (current === entry.hash) {
-    process.stdout.write(`〇 ${relPath}: pristine\n`);
-    process.exit(0);
-  } else {
-    process.stdout.write(`△ ${relPath}: modified (generated by v${entry.generatedByVersion || '?'})\n`);
-    process.exit(1);
-  }
-}
-
-// ── list ─────────────────────────────────────────────────────────────────────
-
-if (subcmd === 'list') {
-  const modifiedOnly = args.includes('--modified');
-  const manifest = readManifest();
-  const files = manifest.files || {};
-
-  if (Object.keys(files).length === 0) {
-    process.stdout.write('── No files tracked.\n');
-    process.exit(0);
-  }
-
-  const rows = [];
-  for (const [relPath, entry] of Object.entries(files)) {
-    const status = fileStatus(relPath, entry);
-    if (modifiedOnly && status === 'pristine') continue;
-    rows.push({
-      symbol: STATUS_SYMBOL[status],
-      status,
-      relPath,
-      version: entry.generatedByVersion || '—',
-      date: entry.generatedAt ? entry.generatedAt.slice(0, 10) : '—',
-    });
-  }
-
-  if (rows.length === 0) {
-    process.stdout.write('〇 All tracked files are pristine.\n');
-    process.exit(0);
-  }
-
-  process.stdout.write('| Status | File | Version | Date |\n');
-  process.stdout.write('|--------|------|---------|------|\n');
-  for (const r of rows) {
-    process.stdout.write(`| ${r.symbol} ${r.status} | \`${r.relPath}\` | ${r.version} | ${r.date} |\n`);
-  }
-  process.exit(0);
-}
-
-// ── status ───────────────────────────────────────────────────────────────────
-
-if (subcmd === 'status') {
-  const manifest = readManifest();
-  const files = manifest.files || {};
-  let pristine = 0, modified = 0, missing = 0;
-  for (const [relPath, entry] of Object.entries(files)) {
-    const s = fileStatus(relPath, entry);
-    if (s === 'pristine') pristine++;
-    else if (s === 'modified') modified++;
-    else missing++;
-  }
-  const total = pristine + modified + missing;
-  if (total === 0) {
-    process.stdout.write('── No files tracked.\n');
-    process.exit(0);
-  }
-  process.stdout.write(`── ${total} file(s) tracked\n`);
-  if (pristine > 0) process.stdout.write(`〇 ${pristine} pristine\n`);
-  if (modified > 0) process.stdout.write(`△ ${modified} modified\n`);
-  if (missing  > 0) process.stdout.write(`× ${missing} missing\n`);
-  process.exit(0);
-}
-
-// ── remove ───────────────────────────────────────────────────────────────────
-
-if (subcmd === 'remove') {
-  const filePath = args[0];
-  if (!filePath) {
-    process.stderr.write('Usage: generation-manifest remove <path>\n');
-    process.exit(2);
-  }
-  const relPath = toRelPath(filePath);
-  const manifest = readManifest();
-  if (!manifest.files || !manifest.files[relPath]) {
-    process.stderr.write(`× Not tracked: ${relPath}\n`);
-    process.exit(1);
-  }
-  delete manifest.files[relPath];
-  writeManifest(manifest);
-  process.stdout.write(`〇 Removed from tracking: ${relPath}\n`);
-  process.exit(0);
-}
-
-// ── clear-namespace ──────────────────────────────────────────────────────────
-
-if (subcmd === 'clear-namespace') {
-  const prefix = args[0];
-  if (!prefix) {
-    process.stderr.write('Usage: generation-manifest clear-namespace <prefix>\n');
-    process.exit(2);
-  }
-  const validPrefix = (prefix.startsWith('.forge/') || prefix.startsWith('.claude/')) && prefix.endsWith('/');
-  if (!validPrefix) {
-    process.stderr.write('Usage error: prefix must start with .forge/ or .claude/ and end with /\n');
-    process.exit(2);
-  }
-  const manifest = readManifest();
-  const files = manifest.files || {};
-  const keys = Object.keys(files).filter(k => k.startsWith(prefix));
-  if (keys.length === 0) {
-    process.stdout.write(`── No entries matching ${prefix}\n`);
-  } else {
-    for (const k of keys) delete files[k];
-    writeManifest(manifest);
-    process.stdout.write(`〇 Cleared ${keys.length} entries matching ${prefix}\n`);
-  }
-  process.exit(0);
-}
-
-process.stderr.write(`× Unknown subcommand: ${subcmd}\n`);
-process.exit(2);
-} // end if (require.main === module)

package/dist/forge-payload/.tools/lib/forge-root.cjs

@@ -1,59 +0,0 @@
-'use strict';
-
-// Forge shared helper: resolveForgeRoot
-// FR-001: 3-tier priority resolution for FORGE_ROOT with actionable error.
-//
-// Resolution order:
-//   1. FORGE_ROOT env var — accepted only if ${FORGE_ROOT}/.claude-plugin/plugin.json exists
-//   2. __dirname/.. — the parent of this module's directory (tools/lib -> forge root)
-//   3. Actionable error listing all checked paths
-//
-// This follows the same pattern as project-root.cjs (library module pattern):
-//   - Export functions, no require.main === module CLI block
-//   - Throw errors, don't call process.exit
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Resolve the Forge plugin root directory.
- *
- * @param {string} [envForgeRoot] - Value of FORGE_ROOT environment variable.
- *   If provided and points to a directory containing .claude-plugin/plugin.json,
- *   it is accepted. If provided but plugin.json is missing, resolution falls
- *   through to the __dirname fallback. If omitted/undefined, falls through.
- * @returns {string} Absolute path to the Forge plugin root.
- * @throws {Error} When no valid resolution path is found, with a message listing
- *   all paths that were checked.
- */
-function resolveForgeRoot(envForgeRoot) {
-  const checkedPaths = [];
-
-  // Tier 1: Environment variable — only accepted if plugin.json exists
-  if (envForgeRoot) {
-    const pluginJsonPath = path.join(envForgeRoot, '.claude-plugin', 'plugin.json');
-    checkedPaths.push(pluginJsonPath);
-    if (fs.existsSync(pluginJsonPath)) {
-      return envForgeRoot;
-    }
-    // Env var provided but doesn't point to a valid plugin root — fall through
-  }
-
-  // Tier 2: __dirname/../.. — the standard layout (forge/forge/tools/lib/ -> forge/forge/)
-  // This module lives in tools/lib/, so going up two directories reaches the plugin root.
-  const fallbackRoot = path.resolve(path.join(__dirname, '..', '..'));
-  const fallbackPluginJson = path.join(fallbackRoot, '.claude-plugin', 'plugin.json');
-  checkedPaths.push(fallbackPluginJson);
-  if (fs.existsSync(fallbackPluginJson)) {
-    return fallbackRoot;
-  }
-
-  // Tier 3: Actionable error
-  throw new Error(
-    `Cannot resolve Forge plugin root. Checked paths:\n` +
-    checkedPaths.map(p => `  - ${p}`).join('\n') +
-    '\nSet FORGE_ROOT to a directory containing .claude-plugin/plugin.json'
-  );
-}
-
-module.exports = { resolveForgeRoot };

package/dist/forge-payload/.tools/lib/paths.cjs

@@ -1,29 +0,0 @@
-'use strict';
-
-/**
- * paths.cjs — Shared path-computation helpers for Forge tools.
- *
- * Single source of truth for directory-name conventions that must be
- * consistent across substitute-placeholders.cjs, check-structure.cjs, etc.
- *
- * Exported API:
- *   getCommandsSubdir(prefix) — returns prefix.toLowerCase()
- */
-
-/**
- * Compute the commands subdirectory name from a project prefix.
- *
- * The canonical commands subfolder under .claude/commands/ is derived
- * from the project prefix (lowercased), NOT hardcoded as 'forge'.
- *
- * @param {string} prefix — project prefix (e.g. 'ACME', 'FORGE')
- * @returns {string} lowercased prefix (e.g. 'acme', 'forge')
- */
-function getCommandsSubdir(prefix) {
-  if (typeof prefix !== 'string' || prefix.length === 0) {
-    throw new Error('paths.getCommandsSubdir: prefix must be a non-empty string');
-  }
-  return prefix.toLowerCase();
-}
-
-module.exports = { getCommandsSubdir };

package/dist/forge-payload/.tools/lib/pricing.cjs

@@ -1,165 +0,0 @@
-'use strict';
-
-/**
- * pricing.cjs — Shared pricing primitive for Forge cost tooling.
- *
- * Exports:
- *   MODEL_PRICING   - frozen object mapping canonical model name → { input, output, cacheRead, cacheWrite }
- *                     All rates are in USD per token (not per 1M tokens).
- *   canonicalizeModel(model) - normalises model name variants/aliases to canonical form.
- *                              Returns { canonical, contextWindow } or null if unknown.
- *   computeCost(opts)        - computes USD cost from { inputTokens, outputTokens,
- *                              cacheReadTokens, cacheWriteTokens, model }.
- *                              Returns number (may be 0), or null for unknown model.
- *
- * This module is a pure library — no CLI, no process.exit.
- * Published Anthropic pricing (USD/MTok → divide by 1,000,000 for per-token rate):
- *   claude-opus-4-5:   input $15.00, output $75.00, cacheRead $1.50, cacheWrite $18.75
- *   claude-opus-4-7:   input $15.00, output $75.00, cacheRead $1.50, cacheWrite $18.75
- *   claude-sonnet-4-5: input $3.00,  output $15.00, cacheRead $0.30, cacheWrite $3.75
- *   claude-sonnet-4-6: input $3.00,  output $15.00, cacheRead $0.30, cacheWrite $3.75
- *   claude-haiku-3-5:  input $0.80,  output $4.00,  cacheRead $0.08, cacheWrite $1.00
- */
-
-// All rates in USD per token (divide MTok rate by 1,000,000)
-const MODEL_PRICING = Object.freeze({
-  'claude-opus-4-5': {
-    input:      15.00  / 1_000_000,
-    output:     75.00  / 1_000_000,
-    cacheRead:   1.50  / 1_000_000,
-    cacheWrite: 18.75  / 1_000_000,
-  },
-  'claude-opus-4-7': {
-    input:      15.00  / 1_000_000,
-    output:     75.00  / 1_000_000,
-    cacheRead:   1.50  / 1_000_000,
-    cacheWrite: 18.75  / 1_000_000,
-  },
-  'claude-sonnet-4-5': {
-    input:       3.00  / 1_000_000,
-    output:     15.00  / 1_000_000,
-    cacheRead:   0.30  / 1_000_000,
-    cacheWrite:  3.75  / 1_000_000,
-  },
-  'claude-sonnet-4-6': {
-    input:       3.00  / 1_000_000,
-    output:     15.00  / 1_000_000,
-    cacheRead:   0.30  / 1_000_000,
-    cacheWrite:  3.75  / 1_000_000,
-  },
-  'claude-haiku-3-5': {
-    input:       0.80  / 1_000_000,
-    output:      4.00  / 1_000_000,
-    cacheRead:   0.08  / 1_000_000,
-    cacheWrite:  1.00  / 1_000_000,
-  },
-});
-
-/**
- * Known model families for canonical resolution.
- * Each entry is [baseCanonical, [...synonymPatterns]]
- * Patterns are tested after lower-casing the input model string.
- * The order matters: more specific patterns must come before more general ones.
- */
-const MODEL_FAMILIES = [
-  // Opus family
-  'claude-opus-4-7',
-  'claude-opus-4-5',
-  // Sonnet family
-  'claude-sonnet-4-6',
-  'claude-sonnet-4-5',
-  // Haiku family
-  'claude-haiku-3-5',
-];
-
-/**
- * canonicalizeModel(model)
- *
- * Given a raw model string (possibly fragmented / aliased), returns:
- *   { canonical: string, contextWindow: string|null }
- * where:
- *   - canonical is one of the keys in MODEL_PRICING
- *   - contextWindow is '1m' when a 1M-context-window variant was detected, otherwise null
- *
- * Returns null if the model cannot be mapped to a known canonical name.
- *
- * Examples:
- *   'claude-sonnet-4-6'    → { canonical: 'claude-sonnet-4-6', contextWindow: null }
- *   'claude-sonnet-4-6-1m' → { canonical: 'claude-sonnet-4-6', contextWindow: '1m' }
- *   'claude-sonnet-4-6[1m]'→ { canonical: 'claude-sonnet-4-6', contextWindow: '1m' }
- *   'sonnet-4-6'           → { canonical: 'claude-sonnet-4-6', contextWindow: null }
- *   'opus-4-7-1m'          → { canonical: 'claude-opus-4-7',   contextWindow: '1m' }
- *   'totally-unknown-9-9'  → null
- */
-function canonicalizeModel(model) {
-  if (model == null || typeof model !== 'string' || model.trim() === '') return null;
-
-  const raw = model.trim();
-
-  // Detect and strip 1m context-window suffix variants:
-  //   -1m suffix   (e.g. claude-sonnet-4-6-1m)
-  //   [1m] suffix  (e.g. claude-sonnet-4-6[1m])
-  let contextWindow = null;
-  let stripped = raw;
-  if (/\[1m\]$/i.test(stripped)) {
-    contextWindow = '1m';
-    stripped = stripped.replace(/\[1m\]$/i, '').replace(/-+$/, '');
-  } else if (/-1m$/i.test(stripped)) {
-    contextWindow = '1m';
-    stripped = stripped.replace(/-1m$/i, '');
-  }
-
-  // Normalise to lowercase for matching
-  const lower = stripped.toLowerCase();
-
-  for (const canonical of MODEL_FAMILIES) {
-    // Exact match (after stripping)
-    if (lower === canonical) {
-      return { canonical, contextWindow };
-    }
-    // Short alias: canonical without leading 'claude-'
-    const short = canonical.replace(/^claude-/, '');
-    if (lower === short) {
-      return { canonical, contextWindow };
-    }
-    // Contains the canonical family segment (e.g. 'claude-sonnet-4-6' in a longer variant)
-    if (lower.includes(canonical)) {
-      return { canonical, contextWindow };
-    }
-  }
-
-  return null;
-}
-
-/**
- * computeCost({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, model })
- *
- * Returns the estimated USD cost as a number, or null if the model is unknown.
- * Returns 0 (not null) when all token counts are zero and the model is known.
- * Never returns a negative number.
- *
- * @param {object} opts
- * @param {number} opts.inputTokens
- * @param {number} opts.outputTokens
- * @param {number} opts.cacheReadTokens
- * @param {number} opts.cacheWriteTokens
- * @param {string} opts.model  - raw model string (will be canonicalized)
- * @returns {number|null}
- */
-function computeCost({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, model }) {
-  const canonResult = canonicalizeModel(model);
-  if (canonResult === null) return null;
-
-  const rates = MODEL_PRICING[canonResult.canonical];
-  if (!rates) return null;
-
-  const cost =
-    (inputTokens      || 0) * rates.input +
-    (outputTokens     || 0) * rates.output +
-    (cacheReadTokens  || 0) * rates.cacheRead +
-    (cacheWriteTokens || 0) * rates.cacheWrite;
-
-  return Math.max(0, cost);
-}
-
-module.exports = { MODEL_PRICING, canonicalizeModel, computeCost };

package/dist/forge-payload/.tools/lib/project-root.cjs

@@ -1,32 +0,0 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Walk up from startDir to find the project root (directory containing .forge/config.json).
- * @param {string} [startDir] - Directory to start searching from. Defaults to process.cwd().
- * @returns {string|null} Absolute path to the project root, or null if not found.
- */
-function findProjectRoot(startDir) {
-  let dir = path.resolve(startDir || process.cwd());
-  const root = path.parse(dir).root;
-
-  while (dir !== root) {
-    const configPath = path.join(dir, '.forge', 'config.json');
-    if (fs.existsSync(configPath)) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-
-  // Check root directory as well
-  const rootConfigPath = path.join(root, '.forge', 'config.json');
-  if (fs.existsSync(rootConfigPath)) {
-    return root;
-  }
-
-  return null;
-}
-
-module.exports = { findProjectRoot };

package/dist/forge-payload/.tools/lib/result.js

@@ -1,40 +0,0 @@
-'use strict';
-
-// Structured Result helpers for Forge CJS module APIs.
-//
-// Pattern: every exported function that can fail returns either
-//   { ok: true, value }              — success
-//   { ok: false, code, message }     — failure
-//
-// Code is always a string from RESULT_CODES, never a magic literal.
-
-const RESULT_CODES = {
-  // collate.cjs — resolveTaskDir
-  MISSING_DIR:      'MISSING_DIR',      // no matching task directory found on disk
-
-  // estimate-usage.cjs — estimateTokens
-  E_ZERO_DURATION:    'E_ZERO_DURATION',    // durationMinutes is exactly 0
-  E_MISSING_DURATION: 'E_MISSING_DURATION', // durationMinutes is null or undefined
-};
-
-/**
- * Wrap a success value in a Result.
- * @template T
- * @param {T} [value]
- * @returns {{ ok: true, value: T }}
- */
-function ok(value) {
-  return { ok: true, value };
-}
-
-/**
- * Wrap an error in a Result.
- * @param {string} code  — one of RESULT_CODES
- * @param {string} message — human-readable explanation
- * @returns {{ ok: false, code: string, message: string }}
- */
-function fail(code, message) {
-  return { ok: false, code, message };
-}
-
-module.exports = { ok, fail, RESULT_CODES };