plugin-updater 1.1.2 → 1.2.0

package/README.md

@@ -29,8 +29,8 @@ flowchart TD
 
     %% External & Storage
     subgraph Storage_and_Network [Storage & External]
-        GH_REPOS[GitHub (intisy/plugin-*)]
-        LOCAL_WORKSPACE[(.config/github/repos/intisy/)]
+        GH_REPOS[GitHub (intisy-ai/plugin-*)]
+        LOCAL_WORKSPACE[(.config/github/repos/intisy-ai/)]
         CC_PLUGINS[(.claude/plugin/)]
         OC_PLUGINS[(.config/opencode/plugin/)]
         
@@ -41,17 +41,32 @@ flowchart TD
     end
 ```
 
+## Structure
+
+- `src/` — TypeScript source (`index` engine + `git`, `npm`, `deploy`, `config`, `log`, `env`, `syncbridge`, `cli`, `commands`).
+- `core/` — git submodule ([`intisy-ai/core`](https://github.com/intisy-ai/core)): shared config + the cross-app command framework, bundled to `core/dist/index.js`.
+- `dist/` — compiled output (generated; not committed). `dist/index.js` is the plugin entry + the `node … config` CLI; `dist/cli.js` is the `plugin-updater` bin.
+
+## Installation
+
+plugin-updater is the one plugin added directly to OpenCode's `opencode.jsonc` (every other plugin goes through `plugins.json`); the loaders also resolve and run it on startup. To add it manually:
+```bash
+npm install -g plugin-updater
+plugin-updater add https://github.com/intisy-ai/<plugin>      # register a git plugin
+plugin-updater add https://github.com/intisy-ai/<plugin> --sync  # …and mirror it to the other app
+```
+
 ## Cross-app plugin sync (`sync: true`)
 
-A `plugins.json` entry flagged `sync: true` is mirrored into the **other** app's `plugins.json`, so a plugin enabled in OpenCode is also installed in Claude Code (and vice versa). At the start of `earlyLaunch`, plugin-updater loads [sync-bridge](https://github.com/intisy/sync-bridge)'s library bundle (`dist/lib.js`) and calls `syncPlugins()`, then re-reads the list so a freshly-synced-in plugin is cloned and built in the **same** launch. It is additive (never removes) and a no-op when sync-bridge isn't installed.
+A `plugins.json` entry flagged `sync: true` is mirrored into the **other** app's `plugins.json`, so a plugin enabled in OpenCode is also installed in Claude Code (and vice versa). At the start of `earlyLaunch`, plugin-updater loads [sync-bridge](https://github.com/intisy-ai/sync-bridge)'s library bundle (`dist/lib.js`) and calls `syncPlugins()`, then re-reads the list so a freshly-synced-in plugin is cloned and built in the **same** launch. It is additive (never removes) and a no-op when sync-bridge isn't installed.
 
 ```jsonc
-{ "name": "antigravity-auth", "url": "https://github.com/intisy/antigravity-auth", "enabled": true, "autoUpdate": false, "sync": true }
+{ "name": "antigravity-auth", "url": "https://github.com/intisy-ai/antigravity-auth", "enabled": true, "autoUpdate": false, "sync": true }
 ```
 
 Set it from the CLI with `--sync`:
 ```bash
-plugin-updater add https://github.com/intisy/antigravity-auth --sync
+plugin-updater add https://github.com/intisy-ai/antigravity-auth --sync
 ```
 
 ## API
@@ -64,6 +79,33 @@ plugin-updater add https://github.com/intisy/antigravity-auth --sync
 | `uninstall(pluginItem)` | Remove repo and deployed files |
 | `registerTests(testApi)` | Register sync verification tests |
 
+## Commands
+
+Deployed automatically to both apps on each `earlyLaunch` (`~/.config/opencode/command/` and `~/.claude/commands/`):
+
+| Command | Description |
+| --- | --- |
+| `/plugin-updater-config` | View/change plugin-updater config: `list`, `get <key>`, `set <key> <value>`. 100% of the config is reachable here. |
+
+(The loaders own `/plugins`; plugin-updater drives the actual install/update lifecycle behind it.)
+
+## Configuration
+
+Config file: `~/.config/opencode/config/plugin-updater.json` (preferred) or `~/.config/opencode/plugin-updater.json` (fallback); same under `~/.claude` for Claude Code.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `logging` | boolean | `true` | Write a per-session log file. Set `false` to disable. |
+
+## Dependencies
+
+- **`core`** (required) — bundled git submodule (config + command framework); no separate install.
+- **`sync-bridge`** (optional) — loaded at runtime for `syncPlugins()`; absent, cross-app sync no-ops.
+
+## Logging
+
+Logs to `~/.config/opencode/logs/YYYY-MM-DD/plugin-updater-HH-MM-SS.log` (Claude: under `~/.claude/`). Set `"logging": false` to disable.
+
 ## License
 
 MIT

package/core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 intisy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/core/README.md

@@ -0,0 +1,84 @@
+# 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
+
+```mermaid
+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`:
+```bash
+git submodule add https://github.com/intisy-ai/core core
+```
+`core` is **not published to npm** — it's a bundled submodule. (Loaders/providers that already carry `core-loader`/`core-auth` can nest `core` inside those, or add it as a second submodule.)
+
+## API
+```ts
+import {
+  getApp, isClaude, getAppConfigDir, existingApps,        // env
+  loadConfig, getConfigValue, setConfigValue, listConfig, // config
+  createLogger, makeWriteLog,                             // log
+  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:
+
+```ts
+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:
+
+```ts
+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` itself has no config. It reads each consuming plugin's `config/<name>.json`
+(preferred) or `<name>.json` (fallback) under the app's config dir.
+
+## 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.
+
+## License
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,2 @@
+export declare function deployUpdaterCommands(): void;
+export declare function maybeRunCli(): Promise<boolean>;

package/dist/commands.js

@@ -0,0 +1,36 @@
+// @ts-nocheck
+// Cross-app slash-command for plugin-updater: /plugin-updater-config (the loaders
+// own /plugins). plugin-updater is an npm package (not deployed at plugin/<name>.js),
+// so the command shells into this same bundle's index.js by its absolute path.
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { runConfigCli, deployCommands } from "../core/dist/index.js";
+const PLUGIN = "plugin-updater";
+// the deployed entry that carries the maybeRunCli guard (dist/index.js, sibling).
+const SELF = join(dirname(fileURLToPath(import.meta.url)), "index.js");
+export function deployUpdaterCommands() {
+    try {
+        deployCommands(PLUGIN, [
+            {
+                name: "plugin-updater-config",
+                description: "View/change plugin-updater configuration",
+                argumentHint: "list | get <key> | set <key> <value>",
+                shell: `node "${SELF}" config $ARGUMENTS`,
+                body: "Above is the plugin-updater config result. Report it; if the user changed a setting, confirm the new value.",
+            },
+        ]);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// If invoked as `node dist/index.js config …`, run the config CLI and return true
+// so the entry exits before the updater/self-activate sequence.
+export async function maybeRunCli() {
+    const argv = process.argv.slice(2);
+    if (argv[0] === "config") {
+        runConfigCli(PLUGIN, argv.slice(1));
+        return true;
+    }
+    return false;
+}

package/dist/index.js

@@ -5,8 +5,15 @@ import { selfUpdate, updateNpmPlugin } from "./npm.js";
 import { updatePlugin } from "./git.js";
 import { deployToExecutionDir } from "./deploy.js";
 import { syncPluginsAcrossApps } from "./syncbridge.js";
+// @ts-ignore — generated bundle, no .d.ts
+import { maybeRunCli, deployUpdaterCommands } from "./commands.js";
 import path from "path";
 import fs from "fs";
+// `node dist/index.js config …` (from the /plugin-updater-config command) runs the
+// config CLI and exits, before the self-activation/updater sequence below.
+if (await maybeRunCli()) {
+    process.exit(0);
+}
 // remove repos/ clones and deployed plugin/ files for plugins no longer in
 // plugins.json, so a removed/renamed plugin stops showing up
 function pruneOrphans(configDir, plugins) {
@@ -57,6 +64,11 @@ export async function earlyLaunch(configDir, plugins) {
         return {};
     setEarlyLaunchConfigDir(configDir);
     writeLog("Starting earlyLaunch updater sequence");
+    // keep the cross-app /plugin-updater-config command deployed (idempotent)
+    try {
+        deployUpdaterCommands();
+    }
+    catch { /* best-effort */ }
     // pull in any `sync: true` plugins from the other app BEFORE building, then
     // re-read the list so a freshly-synced-in plugin is cloned/built this pass.
     await syncPluginsAcrossApps(configDir);
@@ -123,10 +135,12 @@ export async function activate(opencodeHookInput) {
     await earlyLaunch(configDir, gitPlugins);
 }
 // consumers like the loader TUI import this module for its API only — running
-// the full updater sequence on import would print over their screen
-if (process.env.PLUGIN_UPDATER_LIBRARY_MODE !== "1") {
-    // signal loaders (which activate later in the same process) that we are
-    // self-driving updates, so their runEarlyLaunchHooks skips a duplicate pass
+// the full updater sequence on import would print over their screen.
+// The ACTIVATION guard makes self-activation idempotent PER PROCESS: opencode may
+// load plugin-updater as more than one module instance (its npm-plugin copy plus a
+// loader's separately-resolved copy), and each would otherwise run earlyLaunch. The
+// first sets the flag; later instances (and the loaders' runEarlyLaunchHooks) skip.
+if (process.env.PLUGIN_UPDATER_LIBRARY_MODE !== "1" && process.env.PLUGIN_UPDATER_ACTIVATION !== "1") {
     process.env.PLUGIN_UPDATER_ACTIVATION = "1";
     activate();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-updater",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Plugin lifecycle manager for OpenCode and Claude Code launchers",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,7 @@
   "author": "intisy",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/intisy/plugin-updater.git"
+    "url": "git+https://github.com/intisy-ai/plugin-updater.git"
   },
   "keywords": [
     "opencode",
@@ -22,6 +22,7 @@
   ],
   "files": [
     "dist/",
+    "core/dist/",
     "README.md",
     "LICENSE"
   ],
@@ -29,10 +30,11 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "npx esbuild core/src/index.ts --bundle --platform=node --format=esm --outfile=core/dist/index.js && tsc",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "esbuild": "^0.25.12",
     "@types/node": "^22.0.0",
     "typescript": "^5.0.0"
   }