rhachet-roles-bhrain 0.3.0 → 0.5.1

package/dist/roles/reviewer/skills/reflect/reflect.ts

@@ -0,0 +1,356 @@
+import * as fs from 'fs/promises';
+import { BadRequestError } from 'helpful-errors';
+import * as path from 'path';
+
+import type { ReviewerReflectMetrics } from '@src/domain.objects/Reviewer/ReviewerReflectMetrics';
+import { getGitRemoteUrl } from '@src/domain.operations/git/getGitRemoteUrl';
+import { createDraftDirectory } from '@src/domain.operations/reflect/createDraftDirectory';
+import {
+  invokeClaudeCodeForReflect,
+  type ReflectStep1Response,
+} from '@src/domain.operations/reflect/invokeClaudeCodeForReflect';
+import { computeMetricsExpected } from '@src/domain.operations/reflect/metrics/computeMetricsExpected';
+import { computeMetricsRealized } from '@src/domain.operations/reflect/metrics/computeMetricsRealized';
+import { writeLogArtifact } from '@src/domain.operations/reflect/metrics/writeLogArtifact';
+import { compileCitationsMarkdown } from '@src/domain.operations/reflect/step1/compileCitationsMarkdown';
+import { compileReflectStep1Prompt } from '@src/domain.operations/reflect/step1/compileReflectStep1Prompt';
+import { compileReflectStep2Prompt } from '@src/domain.operations/reflect/step2/compileReflectStep2Prompt';
+import { executeManifestOperations } from '@src/domain.operations/reflect/step2/executeManifestOperations';
+import { parseManifestOperations } from '@src/domain.operations/reflect/step2/parseManifestOperations';
+import { validateSourceDirectory } from '@src/domain.operations/reflect/validateSourceDirectory';
+import { validateTargetDirectory } from '@src/domain.operations/reflect/validateTargetDirectory';
+
+/**
+ * .what = result of stepReflect execution
+ * .why = enables caller to inspect reflect outcome and artifacts
+ */
+export type StepReflectResult = {
+  draft: {
+    dir: string;
+    pureDir: string;
+    syncDir: string;
+  };
+  results: {
+    created: number;
+    updated: number;
+    appended: number;
+    omitted: number;
+  };
+  metrics: ReviewerReflectMetrics;
+};
+
+/**
+ * .what = generates ISO timestamp for log directory naming
+ * .why = enables unique, sortable log directories
+ */
+const genLogTimestamp = (): string => {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+};
+
+/**
+ * .what = simple spinner for CLI feedback
+ * .why = shows progress during long-running operations
+ */
+const withSpinner = async <T>(input: {
+  message: string;
+  operation: () => Promise<T>;
+}): Promise<T> => {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const startTime = Date.now();
+  let i = 0;
+
+  // print title once
+  console.log(input.message);
+
+  // render only the elapsed time branch line
+  const render = (frame: string) => {
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    process.stdout.write(`\r   └─ elapsed: ${elapsed}s ${frame}  `);
+  };
+
+  render(frames[0]!);
+  const interval = setInterval(() => {
+    i = (i + 1) % frames.length;
+    render(frames[i]!);
+  }, 100);
+
+  try {
+    const result = await input.operation();
+    clearInterval(interval);
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    process.stdout.write(`\r   └─ elapsed: ${elapsed}s ✓\n\n`);
+    return result;
+  } catch (error) {
+    clearInterval(interval);
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    process.stdout.write(`\r   └─ elapsed: ${elapsed}s ✗\n`);
+    throw error;
+  }
+};
+
+/**
+ * .what = extracts rules from feedback and proposes them to target
+ * .why = core orchestration flow for reviewer.reflect skill
+ */
+export const stepReflect = async (input: {
+  source: string;
+  target: string;
+  mode?: 'soft' | 'hard';
+  force?: boolean;
+  rapid?: boolean;
+}): Promise<StepReflectResult> => {
+  const mode = input.mode ?? 'soft';
+  const force = input.force ?? false;
+  const rapid = input.rapid ?? false;
+
+  // validate source directory and get feedback files
+  const { feedbackFiles } = await validateSourceDirectory({
+    source: input.source,
+  });
+
+  // validate target directory
+  await validateTargetDirectory({ target: input.target, force });
+
+  // get git remote url for citations
+  const remoteUrl = getGitRemoteUrl({ cwd: input.source });
+  if (!remoteUrl) {
+    throw new BadRequestError(
+      'source directory must be a git repository with remote origin',
+      { source: input.source },
+    );
+  }
+
+  // create draft directory
+  const { draftDir, pureDir, syncDir } = await createDraftDirectory({
+    targetDir: input.target,
+  });
+
+  // compile citations markdown
+  const citationsMarkdown = compileCitationsMarkdown({
+    feedbackFiles,
+    cwd: input.source,
+  });
+
+  // write citations.md to draft directory
+  await fs.writeFile(
+    path.join(draftDir, 'citations.md'),
+    citationsMarkdown,
+    'utf-8',
+  );
+
+  // compile step 1 prompt
+  const step1Prompt = await compileReflectStep1Prompt({
+    feedbackFiles,
+    citationsMarkdown,
+    draftDir,
+    cwd: input.source,
+    mode,
+  });
+
+  // compute expected metrics
+  const step2PromptResult = await compileReflectStep2Prompt({
+    targetDir: input.target,
+    draftDir,
+    pureDir,
+    mode,
+    rapid,
+  });
+  const expected = computeMetricsExpected({
+    step1PromptTokens: step1Prompt.tokenEstimate,
+    step2PromptTokens: step2PromptResult.tokenEstimate,
+  });
+
+  // emit metrics.expected
+  console.log(
+    `
+🔭 metrics.expected
+   ├─ files
+   │  └─ feedback: ${feedbackFiles.length}
+   ├─ tokens
+   │  ├─ estimate: ${expected.tokens.toLocaleString()}
+   │  └─ context: ${expected.contextWindowPercent}%
+   └─ cost
+      └─ estimate: $${expected.cost.toFixed(4)}
+`.trim(),
+  );
+
+  // step 1: propose pure rules
+  console.log('');
+  const step1Result = await withSpinner({
+    message: '⛏️  step 1: propose pure rules from feedback...',
+    operation: async () => {
+      // invoke claude-code with step 1 prompt
+      // model writes rules directly to pureDir via Write tool
+      const { response, usage } =
+        await invokeClaudeCodeForReflect<ReflectStep1Response>({
+          prompt: step1Prompt.prompt,
+          cwd: input.source,
+          rapid,
+        });
+
+      // count rules written by enumerating pureDir
+      const pureFiles = await fs.readdir(pureDir).catch(() => []);
+      const rulesProposed = pureFiles.filter((f) =>
+        f.startsWith('rule.'),
+      ).length;
+
+      return {
+        tokens: usage,
+        rulesProposed: rulesProposed || response.rules?.length || 0,
+      };
+    },
+  });
+
+  // re-compile step 2 prompt with actual pure rules
+  const step2PromptFinal = await compileReflectStep2Prompt({
+    targetDir: input.target,
+    draftDir,
+    pureDir,
+    mode,
+    rapid,
+  });
+
+  // step 2: blend proposals with existing rules
+  const step2Result = await withSpinner({
+    message: '🪨 step 2: blend proposals with existing rules...',
+    operation: async () => {
+      // invoke claude-code with step 2 prompt
+      // note: model writes manifest.json directly via Write tool
+      const { usage } = await invokeClaudeCodeForReflect<{ written: boolean }>({
+        prompt: step2PromptFinal.prompt,
+        cwd: input.target,
+        rapid,
+      });
+
+      // read the manifest written by the model
+      const manifestPath = path.join(draftDir, 'manifest.json');
+      const manifestContent = await fs.readFile(manifestPath, 'utf-8');
+
+      return {
+        tokens: usage,
+        manifestContent,
+      };
+    },
+  });
+
+  // parse manifest operations
+  const manifest = parseManifestOperations({
+    content: step2Result.manifestContent,
+  });
+
+  // execute manifest operations
+  const blendResults = await executeManifestOperations({
+    manifest,
+    pureDir,
+    syncDir,
+    targetDir: input.target,
+    log: console,
+  });
+
+  // compute realized metrics
+  const realized = computeMetricsRealized({
+    step1: { tokens: step1Result.tokens },
+    step2: { tokens: step2Result.tokens },
+  });
+
+  // build full metrics object
+  const metrics: ReviewerReflectMetrics = {
+    files: {
+      feedbackCount: feedbackFiles.length,
+      rulesCount:
+        blendResults.created + blendResults.updated + blendResults.appended,
+    },
+    expected,
+    realized,
+  };
+
+  // write log artifact
+  await writeLogArtifact({
+    draftDir,
+    metrics,
+    results: blendResults,
+  });
+
+  // emit metrics.realized
+  console.log(
+    `
+✨ metrics.realized
+   ├─ tokens
+   │  ├─ input: ${realized.total.tokens.input.toLocaleString()}
+   │  └─ output: ${realized.total.tokens.output.toLocaleString()}
+   └─ cost
+      └─ total: $${realized.total.cost.total.toFixed(4)}
+
+🌊 output
+   ├─ draft: ${draftDir.startsWith(process.cwd()) ? path.relative(process.cwd(), draftDir) : draftDir}
+   ├─ pure: ${pureDir.startsWith(process.cwd()) ? path.relative(process.cwd(), pureDir) : pureDir}
+   └─ sync: ${syncDir.startsWith(process.cwd()) ? path.relative(process.cwd(), syncDir) : syncDir}
+
+🪨 results
+   ├─ created: ${blendResults.created}
+   ├─ updated: ${blendResults.updated}
+   ├─ appended: ${blendResults.appended}
+   └─ omitted: ${blendResults.omitted}
+`.trim(),
+  );
+
+  return {
+    draft: {
+      dir: draftDir,
+      pureDir,
+      syncDir,
+    },
+    results: blendResults,
+    metrics,
+  };
+};
+
+/**
+ * .what = CLI entrypoint when run directly
+ * .why = enables ./reflect.sh to invoke this module
+ */
+if (require.main === module) {
+  // parse command line arguments
+  const args = process.argv.slice(2);
+  const parsed: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i]?.replace(/^--/, '');
+    const value = args[i + 1];
+    if (key && value) parsed[key] = value;
+  }
+
+  // validate required arguments
+  if (!parsed.source) {
+    console.error('⛈️ error: --source is required');
+    process.exit(1);
+  }
+  if (!parsed.target) {
+    console.error('⛈️ error: --target is required');
+    process.exit(1);
+  }
+
+  // parse optional arguments
+  const mode = (parsed.mode as 'soft' | 'hard') ?? 'soft';
+  const force = parsed.force === 'true';
+  const rapid = parsed.rapid === 'true';
+
+  // execute reflect
+  void (async () => {
+    try {
+      await stepReflect({
+        source: parsed.source!,
+        target: parsed.target!,
+        mode,
+        force,
+        rapid,
+      });
+    } catch (error) {
+      if (error instanceof BadRequestError) {
+        console.error(`\n⛈️ error: ${error.message}`);
+        process.exit(1);
+      }
+      console.error('⛈️ unexpected error:', error);
+      process.exit(1);
+    }
+  })();
+}

package/dist/roles/thinker/getThinkerBrief.d.ts

@@ -1,6 +1,6 @@
 import type { Artifact } from 'rhachet-artifact';
 import { type GitFile } from 'rhachet-artifact-git';
-import type { BriefOptionThinker } from './getThinkerBrief.Options.codegen';
+import type { BriefOptionThinker } from '../../roles/thinker/getThinkerBrief.Options.codegen';
 /**
  * .what = loads an artifact:brief distilled for the mechanic to reference, from the `briefs` directory
  * .why = enables reusable knowledge downloads for mechanic contexts (e.g., matrix-movie style)

package/dist/roles/thinker/getThinkerRole.js

@@ -2,14 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ROLE_THINKER = void 0;
 const rhachet_1 = require("rhachet");
-const getThinkerBrief_1 = require("./getThinkerBrief");
-const stepArticulate_skill_1 = require("./skills/brief.articulate/stepArticulate.skill");
-const stepCatalogize_skill_1 = require("./skills/brief.catalogize/stepCatalogize.skill");
-const stepDemonstrate_skill_1 = require("./skills/brief.demonstrate/stepDemonstrate.skill");
-const stepCluster_skill_1 = require("./skills/khue.cluster/stepCluster.skill");
-const stepDiverge_skill_1 = require("./skills/khue.diverge/stepDiverge.skill");
-const stepInstantiate_skill_1 = require("./skills/khue.instantiate/stepInstantiate.skill");
-const stepTriage_skill_1 = require("./skills/khue.triage/stepTriage.skill");
+const getThinkerBrief_1 = require("../../roles/thinker/getThinkerBrief");
+const stepArticulate_skill_1 = require("../../roles/thinker/skills/brief.articulate/stepArticulate.skill");
+const stepCatalogize_skill_1 = require("../../roles/thinker/skills/brief.catalogize/stepCatalogize.skill");
+const stepDemonstrate_skill_1 = require("../../roles/thinker/skills/brief.demonstrate/stepDemonstrate.skill");
+const stepCluster_skill_1 = require("../../roles/thinker/skills/khue.cluster/stepCluster.skill");
+const stepDiverge_skill_1 = require("../../roles/thinker/skills/khue.diverge/stepDiverge.skill");
+const stepInstantiate_skill_1 = require("../../roles/thinker/skills/khue.instantiate/stepInstantiate.skill");
+const stepTriage_skill_1 = require("../../roles/thinker/skills/khue.triage/stepTriage.skill");
 exports.ROLE_THINKER = rhachet_1.Role.build({
     slug: 'thinker',
     name: 'Thinker',

package/dist/roles/thinker/getThinkerRole.js.map

@@ -1 +1 @@
-{"version":3,"file":"getThinkerRole.js","sourceRoot":"","sources":["../../../src/roles/thinker/getThinkerRole.ts"],"names":[],"mappings":";;;AAAA,qCAA0C;AAE1C,uDAAoD;AACpD,yFAAkF;AAClF,yFAAkF;AAClF,4FAAqF;AACrF,+EAAwE;AACxE,+EAAwE;AACxE,2FAAoF;AACpF,4EAAqE;AAExD,QAAA,YAAY,GAAS,cAAI,CAAC,KAAK,CAAC;IAC3C,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE;;;;GAIP,CAAC,IAAI,EAAE;IACR,MAAM,EAAE;QACN,mBAAS,CAAC,KAAK,CAAC;YACd,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,iDAAiD;YACzD,KAAK,EAAE,IAAA,iCAAe,EAAC,cAAc,CAAC;SACvC,CAAC;QACF,mBAAS,CAAC,KAAK,CAAC;YACd,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,8CAA8C;YACtD,KAAK,EAAE,IAAA,iCAAe,EAAC,0BAA0B,CAAC;SACnD,CAAC;KACH;IACD,MAAM,EAAE;QACN,IAAI,EAAE,EAAE;QACR,IAAI,EAAE;YACJ,kBAAkB;YAClB,iCAAa;YACb,iCAAa;YACb,+BAAY;YACZ,yCAAiB;YAEjB,kBAAkB;YAClB,uCAAgB;YAChB,yCAAiB;YACjB,uCAAgB;YAEhB,kBAAkB;YAClB,sCAAsC;SACvC;KACF;IACD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;KACvC;CACF,CAAC,CAAC"}
+{"version":3,"file":"getThinkerRole.js","sourceRoot":"","sources":["../../../src/roles/thinker/getThinkerRole.ts"],"names":[],"mappings":";;;AAAA,qCAA0C;AAE1C,wEAAqE;AACrE,0GAAmG;AACnG,0GAAmG;AACnG,6GAAsG;AACtG,gGAAyF;AACzF,gGAAyF;AACzF,4GAAqG;AACrG,6FAAsF;AAEzE,QAAA,YAAY,GAAS,cAAI,CAAC,KAAK,CAAC;IAC3C,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE;;;;GAIP,CAAC,IAAI,EAAE;IACR,MAAM,EAAE;QACN,mBAAS,CAAC,KAAK,CAAC;YACd,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,iDAAiD;YACzD,KAAK,EAAE,IAAA,iCAAe,EAAC,cAAc,CAAC;SACvC,CAAC;QACF,mBAAS,CAAC,KAAK,CAAC;YACd,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,8CAA8C;YACtD,KAAK,EAAE,IAAA,iCAAe,EAAC,0BAA0B,CAAC;SACnD,CAAC;KACH;IACD,MAAM,EAAE;QACN,IAAI,EAAE,EAAE;QACR,IAAI,EAAE;YACJ,kBAAkB;YAClB,iCAAa;YACb,iCAAa;YACb,+BAAY;YACZ,yCAAiB;YAEjB,kBAAkB;YAClB,uCAAgB;YAChB,yCAAiB;YACjB,uCAAgB;YAEhB,kBAAkB;YAClB,sCAAsC;SACvC;KACF;IACD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;KACvC;CACF,CAAC,CAAC"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-bhrain",
   "author": "ehmpathy",
   "description": "reliable thought concept navigation roles, briefs, and skills, via rhachet",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "repository": "ehmpathy/rhachet-roles-bhrain",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-bhrain",
   "keywords": [
@@ -33,7 +33,6 @@
     "test:types": "tsc -p ./tsconfig.json --noEmit",
     "test:format": "npm run test:format:biome",
     "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
-    "test:integration:hold": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
     "test:lint:biome": "biome check --diagnostic-level=error",
     "test:lint:biome:all": "biome check",
     "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
@@ -52,6 +51,7 @@
     "prepare:rhachet": "rhachet init && rhachet roles link --role mechanic && rhachet roles link --role behaver && rhachet roles init --role mechanic"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "0.51.0",
     "@ehmpathy/as-command": "1.0.3",
     "@ehmpathy/uni-time": "1.8.1",
     "as-procedure": "1.1.7",
@@ -67,7 +67,9 @@
     "simple-in-memory-cache": "0.4.0",
     "type-fns": "1.21.0",
     "with-simple-caching": "0.14.2",
-    "wrapper-fns": "1.1.0"
+    "wrapper-fns": "1.1.0",
+    "zod": "3.25.76",
+    "zod-to-json-schema": "3.25.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-code": "2.0.76",