core

The shared foundation every plugin in the ecosystem builds on. Consumed as a git submodule and bundled into each plugin (like core-auth / core-loader), so there is no runtime install. It supersedes core-log (whose config + logging API lives here now) and adds app detection, the opencode/claude hook guard, file helpers, and a cross-app command + config-command framework.

Under-the-Hood Architecture

flowchart TD
    PLUGIN["any plugin (utility / provider / loader)"] -->|imports + bundles| CORE["core (this repo, submodule)"]
    CORE --> ENV["env: getApp / getAppConfigDir / existingApps"]
    CORE --> CFG["config: load / get / set / list (config/<name>.json)"]
    CORE --> LOG["log: createLogger / makeWriteLog"]
    CORE --> FILES["files: atomicWrite / readJson / writeJson"]
    CORE --> HOOK["hook: isHookInvocation guard"]
    CORE --> CMD["command: deployCommands / configCommand"]
    CMD -->|writes *.md| OCDIR["~/.config/opencode/command/"]
    CMD -->|writes *.md| CCDIR["~/.claude/commands/"]
    OCDIR -->|/<plugin>-config runs| CLI["node <bundle> config …  (maybeRunConfigCli)"]
    CCDIR -->|/<plugin>-config runs| CLI
    CLI --> CFG

Structure

• src/ — env, config, log, files, hook, command, configcli, index (barrel)
• dist/ — single bundled index.js (generated; not committed). The config CLI ships inside it.

Installation (for a plugin author)

Add as a submodule and bundle it (esbuild bundle: true), importing from ../core/dist/index.js:

git submodule add https://github.com/intisy-ai/core core

core is compiled from the submodule, and published to npm as @intisy-ai/core so a plugin installed from npm can resolve it as a dependency instead of inlining a copy. (Loaders/providers that already carry core-loader/core-auth can nest core inside those, or add it as a second submodule.)

API

import {
  getApp, getAppConfigDir, existingApps,                             // env
  loadConfig, defineConfig, getConfigDefaults, getConfigValue, setConfigValue, listConfig, // config
  createLogger, makeWriteLog, globalSetting,                        // log + global settings
  atomicWrite, readJson, writeJson, ensureDir,                      // files
  isHookInvocation,                                                 // hook guard
  deployCommands, configCommand, maybeRunConfigCli,                 // commands
} from "../core/dist/index.js";

Commands (work in both opencode and Claude Code)

Both apps read markdown slash-commands from a directory (<cfg>/command/ for opencode, <cfg>/commands/ for claude). deployCommands(pluginName, defs) writes each command to both, so one definition works everywhere. A command may run a shell line whose output is injected, and {{BUNDLE}} resolves to the plugin's deployed file:

import { deployCommands, configCommand } from "../core/dist/index.js";
deployCommands("wakatime-sync", [
  configCommand("wakatime-sync"),                         // /wakatime-sync-config (100% config)
  { name: "wakatime", description: "Today's tracked time", shell: 'node "{{BUNDLE}}" today' },
]);

100% configurable via commands

configCommand(name) generates a /<name>-config command with list | get <key> | set <key> <value>. It shells into the plugin's own bundle, which must call maybeRunConfigCli at the top of its entry:

import { maybeRunConfigCli } from "../core/dist/index.js";
if (maybeRunConfigCli("wakatime-sync")) { /* ran as `node bundle config …`; stop here */ }
else { /* normal plugin activation */ }

Every key in config/<name>.json is then reachable (set coerces true/false/numbers/JSON).

Configuration

core is the single config system for the ecosystem (don't hand-roll config reading):

• loadConfig(name) / getConfigValue / setConfigValue / listConfig / coerce read & write the consuming plugin's config/<name>.json (preferred) or <name>.json (fallback).
• defineConfig(name, defaults) — call on plugin load (BEFORE the maybeRunConfigCli guard) to register a plugin's settings + defaults. Writes nothing — launching never creates a config file. Returns the effective config (defaults + on-disk); getConfigDefaults(name) reads the registered defaults.
• Settings are editable through the loader (Plugins → Configure), which discovers core-plugins via node <bundle> config schema and saves with config set — the only thing that writes a file.
• globalSetting(key, fallback) — reads the GLOBAL config/settings.json (the opencode.json-equivalent; each app home has its own). Currently holds logConsole (mirror logs to the console), logColor, and the activity retention knobs activityMaxBytes / activityMaxDays (0 = unlimited, the default; history is kept forever unless a limit is set) plus activityMinImpact.

Logging

Via createLogger(name) / makeWriteLog(name) → <configDir>/logs/YYYY-MM-DD/<name>-HH-MM-SS.log, toggle with "logging": false in the plugin's config.

teavm-build.mjs (generic TeaVM build harness)

A standalone Node script (not part of the bundled dist/index.js API — invoked directly from a plugin's build script) that runs a Gradle TeaVM generateJavaScript task for a provider's Java module and copies the emitted ESM to a stable path so esbuild can bundle it alongside the provider's TS. Introduced for stub-auth (Phase 4 Task 5, the JS half of the shared-Java model); reusable as-is by any provider with a TeaVM-compiled module (e.g. claude-code-auth/antigravity-auth Task 6) — nothing in the script is provider-specific. Vendored here so every plugin build reaches it reproducibly (via the core submodule) in CI, agentbox, and fresh clones alike.

Contract: runs ./gradlew <module>:<task> inside --java-dir, locates the single non-sourcemap .js file under <java-dir>/<module-dir>/build/generated/teavm/js/, and copies it (plus its .map, if present) to --out. Fails loudly if the java dir/gradle wrapper is missing, the generated-js directory doesn't exist after the build, more/fewer than one .js file is found, or the staged output is empty.

Usage (run from the consuming package's own directory, with core as its submodule):

node core/teavm-build.mjs --java-dir java --module :stub-teavm --out src/generated/stub-provider.teavm.js

Flags: --java-dir / --module / --out (all required), --task (default generateJavaScript), --module-dir (default --module minus its leading :), --skip-build (re-copy the last-generated output without re-running Gradle).

License

MIT