eai-cli 0.0.0-bootstrap.0

package/resources/gofer/node-scripts/gofer-performance-report.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DEFAULT_ROOT = path.resolve(__dirname, '..', '..', '..');
+const DEFAULT_TOKEN_DIVISOR = 4;
+
+const FILE_EXTENSIONS = new Set([
+  '.md',
+  '.json',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.txt',
+  '.mjs',
+  '.js',
+  '.ts',
+  '.tsx',
+  '.sh',
+]);
+
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  'dist-repro',
+  'coverage',
+  'test-results',
+  '.cache',
+  '.pytest_cache',
+  '.qagent',
+  '.qagent-workspace',
+]);
+
+const BUCKETS = [
+  {
+    name: 'active-specs',
+    label: 'Active specs',
+    roots: ['.specify/specs'],
+    include: (relativePath) => !relativePath.split('/').some((segment) => segment.startsWith('_')),
+  },
+  {
+    name: 'archived-specs',
+    label: 'Archived specs',
+    roots: ['.specify/specs'],
+    include: (relativePath) => relativePath.split('/').some((segment) => segment.startsWith('_')),
+  },
+  {
+    name: 'memory',
+    label: 'Memory',
+    roots: ['.specify/memory'],
+  },
+  {
+    name: 'system-files',
+    label: 'System files',
+    files: ['AGENTS.md', 'CLAUDE.md', 'README.md', '.specify/.gofer-version'],
+  },
+  {
+    name: 'generated-surfaces',
+    label: 'Generated command surfaces',
+    roots: [
+      '.claude/commands',
+      '.agents/skills',
+      '.system/skills',
+      '.github/prompts',
+      '.gemini',
+      '.claude-plugin',
+      '.codex-plugin',
+      'extension/resources',
+    ],
+  },
+  {
+    name: 'hooks',
+    label: 'Hook scripts',
+    roots: ['.specify/scripts/hooks'],
+  },
+  {
+    name: 'workflow-source',
+    label: 'Generic workflow source',
+    roots: ['src', 'extension/src/services', 'language-server/src'],
+  },
+];
+
+function parseArgs(argv) {
+  const args = {
+    root: DEFAULT_ROOT,
+    json: false,
+    tokenDivisor: DEFAULT_TOKEN_DIVISOR,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--root') {
+      args.root = path.resolve(argv[index + 1] ?? '');
+      index += 1;
+    } else if (arg === '--json') {
+      args.json = true;
+    } else if (arg === '--token-divisor') {
+      args.tokenDivisor = Number(argv[index + 1] ?? DEFAULT_TOKEN_DIVISOR);
+      index += 1;
+    } else if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    }
+  }
+  return args;
+}
+
+function shouldReadFile(filePath) {
+  return FILE_EXTENSIONS.has(path.extname(filePath));
+}
+
+function toPortablePath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function estimateTokens(chars, tokenDivisor) {
+  return Math.ceil(chars / tokenDivisor);
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function walkFiles(root, relativeRoot = '') {
+  const files = [];
+  const absoluteRoot = path.join(root, relativeRoot);
+  if (!(await pathExists(absoluteRoot))) {
+    return files;
+  }
+
+  const stack = [absoluteRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const child = path.join(current, entry.name);
+      const relativePath = toPortablePath(path.relative(root, child));
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          stack.push(child);
+        }
+      } else if (entry.isFile() && shouldReadFile(child)) {
+        files.push(relativePath);
+      }
+    }
+  }
+
+  return files.sort();
+}
+
+async function summarizeFiles(root, files, tokenDivisor) {
+  let chars = 0;
+  for (const relativePath of files) {
+    try {
+      const stat = await fs.stat(path.join(root, relativePath));
+      chars += stat.size;
+    } catch {
+      // Ignore files removed during scan.
+    }
+  }
+  return {
+    filesScanned: files.length,
+    chars,
+    estimatedTokens: estimateTokens(chars, tokenDivisor),
+  };
+}
+
+async function measureOperation(name, fn, operations) {
+  const start = performance.now();
+  const result = await fn();
+  const durationMs = Math.round((performance.now() - start) * 100) / 100;
+  operations.push({ name, durationMs });
+  return { result, durationMs };
+}
+
+async function collectBucket(root, bucket, tokenDivisor, operations) {
+  const { result: files, durationMs } = await measureOperation(
+    `discover:${bucket.name}`,
+    async () => {
+      const found = [];
+      for (const relativeRoot of bucket.roots ?? []) {
+        found.push(...(await walkFiles(root, relativeRoot)));
+      }
+      for (const relativeFile of bucket.files ?? []) {
+        if (await pathExists(path.join(root, relativeFile))) {
+          found.push(relativeFile);
+        }
+      }
+      const uniqueFiles = [...new Set(found)];
+      return bucket.include ? uniqueFiles.filter((file) => bucket.include(file)) : uniqueFiles;
+    },
+    operations
+  );
+
+  const { result: summary } = await measureOperation(
+    `estimate:${bucket.name}`,
+    () => summarizeFiles(root, files, tokenDivisor),
+    operations
+  );
+
+  return {
+    name: bucket.name,
+    label: bucket.label,
+    ...summary,
+    discoverMs: durationMs,
+  };
+}
+
+async function generatePerformanceReport(options = {}) {
+  const root = options.root ?? DEFAULT_ROOT;
+  const tokenDivisor = options.tokenDivisor ?? DEFAULT_TOKEN_DIVISOR;
+  const startedAt = performance.now();
+  const operations = [];
+  const buckets = [];
+
+  for (const bucket of BUCKETS) {
+    buckets.push(await collectBucket(root, bucket, tokenDivisor, operations));
+  }
+
+  const totals = buckets.reduce(
+    (acc, bucket) => ({
+      filesScanned: acc.filesScanned + bucket.filesScanned,
+      chars: acc.chars + bucket.chars,
+      estimatedTokens: acc.estimatedTokens + bucket.estimatedTokens,
+    }),
+    { filesScanned: 0, chars: 0, estimatedTokens: 0 }
+  );
+
+  const wallClockMs = Math.round((performance.now() - startedAt) * 100) / 100;
+  return {
+    generatedAt: new Date().toISOString(),
+    rootLabel: '${workspaceFolder}',
+    wallClockMs,
+    totals,
+    buckets,
+    topSlowOperations: operations
+      .sort((left, right) => right.durationMs - left.durationMs)
+      .slice(0, 10),
+  };
+}
+
+function formatMarkdown(report) {
+  const lines = [
+    '# Gofer Performance Baseline',
+    '',
+    `Generated: ${report.generatedAt}`,
+    `Workspace: ${report.rootLabel}`,
+    `Wall-clock: ${report.wallClockMs} ms`,
+    `Files scanned: ${report.totals.filesScanned}`,
+    `Estimated tokens: ${report.totals.estimatedTokens}`,
+    '',
+    '| Bucket | Files | Chars | Estimated Tokens | Discovery ms |',
+    '| --- | ---: | ---: | ---: | ---: |',
+  ];
+
+  for (const bucket of report.buckets) {
+    lines.push(
+      `| ${bucket.label} | ${bucket.filesScanned} | ${bucket.chars} | ${bucket.estimatedTokens} | ${bucket.discoverMs} |`
+    );
+  }
+
+  lines.push('', '## Top Slow Operations', '', '| Operation | ms |', '| --- | ---: |');
+  for (const operation of report.topSlowOperations) {
+    lines.push(`| ${operation.name} | ${operation.durationMs} |`);
+  }
+
+  return lines.join('\n');
+}
+
+if (__filename === path.resolve(process.argv[1] ?? '')) {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(`Usage: node .specify/scripts/node/gofer-performance-report.mjs [--root <path>] [--json]
+
+Produces a repeatable Gofer performance baseline with wall-clock timing,
+files scanned, token estimates, and top slow operations.`);
+    process.exit(0);
+  }
+
+  const report = await generatePerformanceReport(args);
+  console.log(args.json ? JSON.stringify(report, null, 2) : formatMarkdown(report));
+}
+
+export {
+  BUCKETS,
+  collectBucket,
+  estimateTokens,
+  formatMarkdown,
+  generatePerformanceReport,
+  parseArgs,
+  walkFiles,
+};

package/resources/gofer/node-scripts/gofer-workspace-bootstrap.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import {
+  bootstrapWorkspace,
+  findWorkspaceRoot,
+  normalizeHost,
+  scriptRootFromUrl,
+} from './workspace-bootstrap-lib.mjs';
+
+function parseArgs(argv) {
+  const args = {
+    workspace: process.cwd(),
+    host: 'auto',
+    dryRun: false,
+    includeMirrors: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--workspace' && argv[i + 1]) {
+      args.workspace = argv[++i];
+    } else if (arg === '--host' && argv[i + 1]) {
+      args.host = argv[++i];
+    } else if (arg === '--dry-run') {
+      args.dryRun = true;
+    } else if (arg === '--include-mirrors') {
+      args.includeMirrors = true;
+    }
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const workspaceRoot = await findWorkspaceRoot(path.resolve(args.workspace));
+  const sourceRoot = scriptRootFromUrl(import.meta.url);
+
+  const result = await bootstrapWorkspace({
+    workspaceRoot,
+    host: normalizeHost(args.host),
+    sourceRoot,
+    dryRun: args.dryRun,
+    includeMirrors: args.includeMirrors,
+  });
+
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exit(result.status === 'healthy' ? 0 : 2);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+

package/resources/gofer/node-scripts/gofer-workspace-check.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import {
+  checkWorkspaceState,
+  findWorkspaceRoot,
+  formatWorkspaceCheckReport,
+  normalizeHost,
+  scriptRootFromUrl,
+} from './workspace-bootstrap-lib.mjs';
+
+function parseArgs(argv) {
+  const args = {
+    workspace: process.cwd(),
+    host: 'auto',
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--workspace' && argv[i + 1]) {
+      args.workspace = argv[++i];
+    } else if (arg === '--host' && argv[i + 1]) {
+      args.host = argv[++i];
+    } else if (arg === '--json') {
+      args.json = true;
+    }
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const workspaceRoot = await findWorkspaceRoot(path.resolve(args.workspace));
+  const sourceRoot = scriptRootFromUrl(import.meta.url);
+  const report = await checkWorkspaceState({
+    workspaceRoot,
+    host: normalizeHost(args.host),
+    sourceRoot,
+  });
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${formatWorkspaceCheckReport(report)}\n`);
+  }
+
+  process.exit(report.status === 'healthy' ? 0 : 2);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+

package/resources/gofer/node-scripts/lib/ai-leverage-tagger.mjs

@@ -0,0 +1,103 @@
+/**
+ * ai-leverage-tagger.mjs
+ *
+ * Implements the 4-verb AI-leverage taxonomy used across persona-pack visuals.
+ *
+ * The taxonomy is enforced everywhere a TO-BE value-stream step appears:
+ *   - Replace  : AI fully replaces a step that a human used to do.
+ *   - Augment  : AI helps a human do a step better/faster (human in the loop).
+ *   - Automate : Step runs unattended on a schedule or trigger (no human).
+ *   - Observe  : AI watches/monitors only — no action taken.
+ *
+ * `tagVerb()` applies a keyword heuristic to a free-text step description and
+ * returns one of the four valid verbs (defaulting to "Augment" when nothing
+ * matches — the most common case for human-in-the-loop AI work).
+ *
+ * `validateVerb()` is the strict gate used by the persona-pack completeness
+ * check; it throws when the input is not exactly one of the four verbs.
+ */
+
+export const VERBS = Object.freeze(['Replace', 'Augment', 'Automate', 'Observe']);
+
+const KEYWORD_RULES = [
+  {
+    verb: 'Replace',
+    patterns: [
+      /\breplace[sd]?\b/i,
+      /\beliminat(e|es|ed|ing)\b/i,
+      /\bremov(e|es|ed|ing)\b/i,
+      /\bsupersed(e|es|ed|ing)\b/i,
+      /\binstead of\b/i,
+    ],
+  },
+  {
+    verb: 'Automate',
+    patterns: [
+      /\bautomat(e|es|ed|ing|ion)\b/i,
+      /\bunattended\b/i,
+      /\bscheduled?\b/i,
+      /\btrigger(ed|s)?\b/i,
+      /\bcron\b/i,
+      /\bwithout (a |any )?human\b/i,
+    ],
+  },
+  {
+    verb: 'Observe',
+    patterns: [
+      /\bobserv(e|es|ed|ing)\b/i,
+      /\bmonitor(s|ed|ing)?\b/i,
+      /\bwatch(es|ed|ing)?\b/i,
+      /\balert(s|ed|ing)?\b/i,
+      /\bdetect(s|ed|ing)?\b/i,
+      /\btrack(s|ed|ing)?\b/i,
+    ],
+  },
+  {
+    verb: 'Augment',
+    patterns: [
+      /\baugment(s|ed|ing)?\b/i,
+      /\bassist(s|ed|ing)?\b/i,
+      /\bsuggest(s|ed|ing|ion|ions)?\b/i,
+      /\brecommend(s|ed|ing|ation|ations)?\b/i,
+      /\bhelp(s|ed|ing)?\b/i,
+      /\bco-?pilot\b/i,
+    ],
+  },
+];
+
+/**
+ * Classify a value-stream step description into one of the four verbs.
+ *
+ * @param {string} stepDescription Free-text step from a TO-BE flowchart.
+ * @returns {'Replace'|'Augment'|'Automate'|'Observe'}
+ */
+export function tagVerb(stepDescription) {
+  if (typeof stepDescription !== 'string' || stepDescription.trim() === '') {
+    return 'Augment';
+  }
+  for (const { verb, patterns } of KEYWORD_RULES) {
+    if (patterns.some((re) => re.test(stepDescription))) {
+      return verb;
+    }
+  }
+  return 'Augment';
+}
+
+/**
+ * Strict validator used by the persona-pack completeness gate. Throws on any
+ * value outside the canonical 4-verb set.
+ *
+ * @param {string} verb Candidate verb.
+ * @returns {true} On success.
+ * @throws {Error} When `verb` is not one of Replace/Augment/Automate/Observe.
+ */
+export function validateVerb(verb) {
+  if (!VERBS.includes(verb)) {
+    throw new Error(
+      `Invalid AI-leverage verb: ${JSON.stringify(verb)}. Expected one of ${VERBS.join(', ')}.`
+    );
+  }
+  return true;
+}
+
+export default { tagVerb, validateVerb, VERBS };

package/resources/gofer/node-scripts/lib/assemble-stakeholder-pack.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * assemble-stakeholder-pack.mjs
+ *
+ * Composes a stakeholder pack from a feature directory's `visuals/`. The
+ * artifact ordering is fixed and deterministic so two consecutive runs with
+ * the same inputs produce byte-identical output (FR-028, NFR-011).
+ *
+ * Order (locked by spec, do not reorder):
+ *   1. impact-canvas.md
+ *   2. c4-context.md
+ *   3. c4-container.md
+ *   4. value-stream-asis.md
+ *   5. value-stream-tobe.md
+ *   6. capability-heatmap.md
+ *   7. bounded-context.md
+ *   8. data-model-erd.md
+ *   9. risk-heatmap.md
+ *  10. roi-projection.md
+ *
+ * Missing files are skipped with a stderr warning; ordering of present files
+ * is unaffected. Output is written to `<featureDir>/stakeholder-pack.md`.
+ *
+ * Public API:
+ *   assembleStakeholderPack(featureDir)
+ *     -> Promise<{ written: string, included: string[], missing: string[] }>
+ *
+ * CLI usage:
+ *   node assemble-stakeholder-pack.mjs <featureDir>
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Locked artifact order. Do not change without updating the spec + tests.
+ */
+export const STAKEHOLDER_PACK_ORDER = Object.freeze([
+  'impact-canvas.md',
+  'c4-context.md',
+  'c4-container.md',
+  'value-stream-asis.md',
+  'value-stream-tobe.md',
+  'capability-heatmap.md',
+  'bounded-context.md',
+  'data-model-erd.md',
+  'risk-heatmap.md',
+  'roi-projection.md',
+]);
+
+const SEPARATOR = '\n\n---\n\n';
+
+/**
+ * @param {string} featureDir Absolute path to the feature directory.
+ * @returns {Promise<{ written: string, included: string[], missing: string[] }>}
+ */
+export async function assembleStakeholderPack(featureDir) {
+  const visualsDir = path.join(featureDir, 'visuals');
+  const included = [];
+  const missing = [];
+  const sections = [];
+
+  for (const name of STAKEHOLDER_PACK_ORDER) {
+    const filePath = path.join(visualsDir, name);
+    try {
+      const content = await readFile(filePath, 'utf8');
+      sections.push(content.trimEnd());
+      included.push(name);
+    } catch (err) {
+      if (err && /** @type {any} */ (err).code === 'ENOENT') {
+        process.stderr.write(
+          `[assemble-stakeholder-pack] skipping missing artifact: ${name}\n`,
+        );
+        missing.push(name);
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  // Compose: each section separated by `---`. Leading separator omitted so
+  // the first section's H1 is not preceded by a horizontal rule.
+  const body = sections.length === 0 ? '' : sections.join(SEPARATOR) + '\n';
+
+  const outputPath = path.join(featureDir, 'stakeholder-pack.md');
+  await writeFile(outputPath, body, 'utf8');
+
+  return { written: outputPath, included, missing };
+}
+
+// CLI entrypoint
+const isMain =
+  process.argv[1] &&
+  (process.argv[1].endsWith('assemble-stakeholder-pack.mjs') ||
+    process.argv[1] === new URL(import.meta.url).pathname);
+
+if (isMain) {
+  const featureDir = process.argv[2];
+  if (!featureDir) {
+    console.error('Usage: assemble-stakeholder-pack.mjs <featureDir>');
+    process.exit(1);
+  }
+  try {
+    const result = await assembleStakeholderPack(path.resolve(featureDir));
+    console.log(`assembled: ${result.written}`);
+    console.log(`included (${result.included.length}): ${result.included.join(', ')}`);
+    if (result.missing.length > 0) {
+      console.log(`missing (${result.missing.length}): ${result.missing.join(', ')}`);
+    }
+  } catch (err) {
+    console.error(`assemble failed: ${err && err.message ? err.message : err}`);
+    process.exit(1);
+  }
+}