Reorganize runtime into explicit layer directories (#153)

Author: MirzaMerdovic

docs/architecture/overview.md

@@ -17,7 +17,7 @@ The current command architecture uses explicit vertical command slices under `sr
 ## Major runtime parts
 
 ### 1. OpenCode plugin entrypoint
-Represented by `src/plugin.ts`, exported from the package at `./plugin`, and consumed by repositories through the `opencode.json` `plugin` array.
+Represented by `src/opencode/plugin.ts`, with OpenCode-specific caller resolution in `src/opencode/context.ts` and tool execution in `src/opencode/tool.ts`, exported from the package at `./plugin`, and consumed by repositories through the `opencode.json` `plugin` array.
 
 Responsibilities:
 - expose the `orfe` tool through `OrfePlugin`
@@ -30,7 +30,7 @@ It must not:
 - pass raw OpenCode runtime objects into the core
 
 ### 2. CLI entrypoint
-Represented by `src/cli.ts` and `src/command.ts`.
+Represented by `src/cli/entrypoint.ts`, `src/cli/run.ts`, `src/cli/parse.ts`, `src/cli/help.ts`, and `src/cli/types.ts`.
 
 Responsibilities:
 - support commandless invocation as a help/noop path
@@ -42,7 +42,7 @@ Responsibilities:
 The CLI is intentionally a thin adapter. It renders root, group, and leaf help from the registered command catalog rather than maintaining a separate hardcoded command map.
 
 ### 3. Core runtime
-Represented by `src/core.ts` plus the command catalog under `src/commands/`.
+Represented by `src/core/run.ts`, `src/core/context.ts`, `src/core/types.ts`, plus the command catalog under `src/commands/`.
 
 Responsibilities:
 - load repo-local config
@@ -55,10 +55,10 @@ Responsibilities:
 - return structured success or typed errors
 
 The core is runtime-agnostic and must remain callable from both CLI and plugin entrypoints.
-It is also the future extension host, but it must preserve the same wrapper/core and plain-data boundaries while doing so.
+It is also the future extension host, but it must preserve the same OpenCode tool/core and plain-data boundaries while doing so.
 
 ### 4. Config layer
-Current examples include `src/config.ts` and `.orfe/config.json`.
+Current examples include `src/config/repo-config.ts`, `src/config/auth-config.ts`, `src/config/project-defaults.ts`, `src/config/repository-ref.ts`, `src/config/shared.ts`, and `.orfe/config.json`.
 
 Responsibilities:
 - hold repo-local non-secret configuration
@@ -81,15 +81,15 @@ Responsibilities:
 - stay below repository workflow policy rather than interpreting ownership or orchestration semantics
 
 ### 6. Auth layer
-Current examples include `src/github.ts` and machine-local auth config.
+Current examples include `src/github/installation-auth.ts`, `src/github/jwt.ts`, and machine-local auth config.
 
 Responsibilities:
 - load machine-local per-bot GitHub App credentials
 - mint installation tokens
 - keep secret-bearing auth details outside repo-local config
 
 ### 7. GitHub adapter layer
-Current examples include the slice handlers under `src/commands/**/handler.ts` and the shared GitHub client factory in `src/github.ts`.
+Current examples include the slice handlers under `src/commands/**/handler.ts` and the shared GitHub client factory in `src/github/client-factory.ts`.
 
 Responsibilities:
 - use Octokit REST where appropriate for issue and PR behavior
@@ -113,13 +113,13 @@ Enabled does not mean validly configured.
 
 ```mermaid
 graph TD
-  Plugin[OpenCode plugin<br/>src/plugin.ts] --> Core[Core runtime<br/>src/core.ts]
-  CLI[CLI entrypoint<br/>src/cli.ts + src/command.ts] --> Core
+  Plugin[OpenCode plugin<br/>src/opencode/plugin.ts + tool.ts + context.ts] --> Core[Core runtime<br/>src/core/run.ts]
+  CLI[CLI entrypoint<br/>src/cli/entrypoint.ts + run.ts + parse.ts + help.ts] --> Core
 
-  Core --> Config[Repo config<br/>src/config.ts]
+  Core --> Config[Repo config<br/>src/config/*.ts]
   Core --> Templates[Templates modules<br/>src/templates/*.ts]
-  Core --> Auth[Caller bot + auth config]
-  Core --> GitHub[GitHub client factory<br/>src/github.ts]
+  Core --> Auth[Caller bot + auth config<br/>src/config/auth-config.ts + src/github/installation-auth.ts]
+  Core --> GitHub[GitHub client factory<br/>src/github/client-factory.ts]
   Core --> Registry[Generic command registry<br/>src/commands/registry/index.ts]
   Core --> Extensions[Installed extensions<br/>optional + namespaced]
 
@@ -213,7 +213,7 @@ To add a new command:
 - register the slice in `src/commands/index.ts`
 - use or extend `<group>/shared.ts` only for helper logic genuinely shared by multiple commands in that group
 
-Command-specific tests live beside the slice by default. Cross-cutting CLI, core, wrapper, plugin, and package-level tests remain in `test/`.
+Command-specific tests live beside the slice by default. Cross-cutting CLI, core, OpenCode tool/plugin, and package-level tests remain in `test/`.
 
 ## Architectural rules to keep in mind
 

docs/orfe/spec.md

@@ -60,7 +60,7 @@ For terminology in this spec:
 
 - npm package name: `@mirzamerdovic/orfe`
 - installed executable name: `orfe`
-- package CLI entrypoint: package `bin.orfe -> dist/cli.js`
+- package CLI entrypoint: package `bin.orfe -> dist/cli/entrypoint.js`
 - primary public distribution is npmjs.org (`https://registry.npmjs.org`)
 - supported invocation path is `npx @mirzamerdovic/orfe`
 - package-artifact installs produced by `npm pack` remain valid for local development

package-lock.json

@@ -4,14 +4,14 @@
   "description": "Generic GitHub operations runtime for humans and agents",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/wrapper.js",
+  "main": "./dist/opencode/tool.js",
   "exports": {
-    ".": "./dist/wrapper.js",
-    "./plugin": "./dist/plugin.js",
-    "./server": "./dist/plugin.js"
+    ".": "./dist/opencode/tool.js",
+    "./plugin": "./dist/opencode/plugin.js",
+    "./server": "./dist/opencode/plugin.js"
   },
   "bin": {
-    "orfe": "./dist/cli.js"
+    "orfe": "./dist/cli/entrypoint.js"
   },
   "files": [
     "dist",

package.json

@@ -1,18 +1,21 @@
 import assert from 'node:assert/strict';
 
 import { test } from 'vitest';
-import { runCliEntrypoint } from './cli.js';
+import { runCliEntrypoint } from './entrypoint.js';
+
+import type { runCli } from './run.js';
 
 test('runCliEntrypoint forwards explicit argv to runCli and sets process.exitCode', async () => {
   const observedCalls: string[][] = [];
   const processStub: { exitCode: number | undefined } = { exitCode: undefined };
+  const runCliImpl: typeof runCli = async (args) => {
+    observedCalls.push(args);
+    return 23;
+  };
 
   const exitCode = await runCliEntrypoint({
     argv: ['issue', 'get', '--issue-number', '14'],
-    runCliImpl: async (args) => {
-      observedCalls.push(args);
-      return 23;
-    },
+    runCliImpl,
     processImpl: processStub,
   });
 
@@ -24,15 +27,16 @@ test('runCliEntrypoint forwards explicit argv to runCli and sets process.exitCod
 test('runCliEntrypoint falls back to process argv tail when argv is omitted', async () => {
   const processStub: { exitCode: number | undefined } = { exitCode: undefined };
   const originalArgv = process.argv;
+  const runCliImpl: typeof runCli = async (args) => {
+    assert.deepEqual(args, ['issue', 'get', '--issue-number', '14']);
+    return 0;
+  };
 
   process.argv = ['/usr/bin/node', '/tmp/orfe', 'issue', 'get', '--issue-number', '14'];
 
   try {
     const exitCode = await runCliEntrypoint({
-      runCliImpl: async (args) => {
-        assert.deepEqual(args, ['issue', 'get', '--issue-number', '14']);
-        return 0;
-      },
+      runCliImpl,
       processImpl: processStub,
     });
 

src/cli.test.ts src/cli/entrypoint.test.tssrc/cli.test.ts renamed to src/cli/entrypoint.test.ts

@@ -2,7 +2,7 @@
 
 import { fileURLToPath } from 'node:url';
 
-import { runCli } from './command.js';
+import { runCli } from './run.js';
 
 export async function runCliEntrypoint(options: {
   argv?: string[];

src/cli.ts src/cli/entrypoint.tssrc/cli.ts renamed to src/cli/entrypoint.ts

@@ -0,0 +1,91 @@
+import { getCliCommonOptions, getGroupDefinitions, listCommandDefinitions, listCommandGroups, type CommandDefinition, type CommandOptionDefinition } from '../commands/registry/index.js';
+
+import type { OrfeCommandGroup } from './types.js';
+
+export function renderRootHelp(): string {
+  const commandGroups = listCommandGroups();
+  const rootExamples = listCommandDefinitions()
+    .flatMap((definition) => definition.examples)
+    .filter((example, index, examples) => example.trim().length > 0 && examples.indexOf(example) === index)
+    .slice(0, 2);
+
+  return [
+    'orfe - generic GitHub operations runtime',
+    '',
+    'Usage:',
+    `  orfe <${commandGroups.join('|')}> <command> [options]`,
+    '  orfe --help',
+    '  orfe --version',
+    '',
+    'Command groups:',
+    ...commandGroups.map((group) => `  ${group}`),
+    '',
+    'Examples:',
+    ...(rootExamples.length > 0 ? rootExamples.map((example) => `  ${example}`) : ['  orfe --help']),
+    '',
+    'Run `orfe <group> --help` for group-specific help.',
+  ].join('\n');
+}
+
+export function renderGroupHelp(group: OrfeCommandGroup): string {
+  const groupDefinitions = getGroupDefinitions(group);
+
+  return [
+    `orfe ${group}`,
+    '',
+    'Usage:',
+    `  orfe ${group} <command> [options]`,
+    '',
+    'Commands:',
+    ...groupDefinitions.map((definition) => `  ${definition.leaf} - ${definition.purpose}`),
+    '',
+    'Example:',
+    `  ${groupDefinitions[0]?.examples[0] ?? `orfe ${group} --help`}`,
+  ].join('\n');
+}
+
+export function renderLeafHelp(commandDefinition: CommandDefinition): string {
+  const requiredOptions = commandDefinition.options.filter((option) => option.required);
+  const optionalOptions = dedupeOptionDefinitions([
+    ...commandDefinition.options.filter((option) => !option.required),
+    ...getCliCommonOptions().filter((option) => !requiredOptions.some((requiredOption) => requiredOption.flag === option.flag)),
+  ]);
+
+  return [
+    `${commandDefinition.name}`,
+    '',
+    `Purpose: ${commandDefinition.purpose}`,
+    `Usage: ${commandDefinition.usage}`,
+    '',
+    'Required options:',
+    ...(requiredOptions.length > 0 ? requiredOptions.map(formatOptionLine) : ['  (none)']),
+    '',
+    'Optional options:',
+    ...optionalOptions.map(formatOptionLine),
+    '',
+    `Success: ${commandDefinition.successSummary}`,
+    '',
+    'Examples:',
+    ...commandDefinition.examples.map((example) => `  ${example}`),
+    '',
+    'JSON success shape example:',
+    `  ${JSON.stringify(commandDefinition.successDataExample)}`,
+  ].join('\n');
+}
+
+function dedupeOptionDefinitions(optionDefinitions: CommandOptionDefinition[]): CommandOptionDefinition[] {
+  const seenFlags = new Set<string>();
+
+  return optionDefinitions.filter((optionDefinition) => {
+    if (seenFlags.has(optionDefinition.flag)) {
+      return false;
+    }
+
+    seenFlags.add(optionDefinition.flag);
+    return true;
+  });
+}
+
+function formatOptionLine(optionDefinition: CommandOptionDefinition): string {
+  return `  ${optionDefinition.flag} - ${optionDefinition.description}`;
+}