@hecer/yoke 0.2.0 → 0.8.0

package/dist/update/check.js

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// Machine-global (not per-project): one cache under the user's home dir.
+export function cachePath() {
+    return join(homedir(), '.yoke', 'update-check.json');
+}
+export function readCache(file = cachePath()) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        if (typeof raw.checkedAt === 'string' && typeof raw.latest === 'string') {
+            return { checkedAt: raw.checkedAt, latest: raw.latest };
+        }
+    }
+    catch { /* malformed — treat as absent */ }
+    return null;
+}
+export function writeCache(cache, file = cachePath()) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(cache));
+}
+// Strict numeric triple compare; prerelease suffixes are stripped (a prerelease
+// of the same triple is not "newer"). Malformed input is never newer.
+export function isNewer(candidate, current) {
+    const triple = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const a = triple(candidate);
+    const b = triple(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+export function isStale(cache, now) {
+    if (!cache)
+        return true;
+    const t = Date.parse(cache.checkedAt);
+    if (!Number.isFinite(t))
+        return true;
+    return now.getTime() - t > CHECK_INTERVAL_MS;
+}
+export function currentYokeVersion() {
+    // src/update/ and dist/update/ both sit two levels below the package root.
+    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+    return pkg.version;
+}
+function spawnDetachedRefresh() {
+    const refresh = fileURLToPath(new URL('./refresh.js', import.meta.url));
+    try {
+        spawn(process.execPath, [refresh], { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch { /* best-effort — next invocation retries */ }
+}
+// Print (to stderr) a one-line hint when a newer version is cached; kick off a
+// detached cache refresh when stale. Silent in CI, --json runs, non-TTY pipes,
+// and under YOKE_NO_UPDATE_CHECK=1. Never throws, never blocks.
+export function maybeNotifyUpdate(currentVersion, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.YOKE_NO_UPDATE_CHECK || env.CI)
+        return;
+    const argv = opts.argv ?? process.argv;
+    if (argv.includes('--json'))
+        return;
+    const tty = opts.tty ?? process.stderr.isTTY === true;
+    if (!tty)
+        return;
+    const cache = readCache(opts.cacheFile);
+    if (isStale(cache, opts.now ?? new Date())) {
+        (opts.spawnRefresh ?? spawnDetachedRefresh)();
+        return;
+    }
+    if (cache && isNewer(cache.latest, currentVersion)) {
+        const print = opts.print ?? ((m) => console.error(m));
+        print(`yoke ${currentVersion} → ${cache.latest} available — run: yoke upgrade   (disable this check: YOKE_NO_UPDATE_CHECK=1)`);
+    }
+}

package/dist/update/refresh.js

@@ -0,0 +1,28 @@
+import { pathToFileURL } from 'node:url';
+import { writeCache } from './check.js';
+// Detached background refresher (spawned by maybeNotifyUpdate when the cache
+// is stale): one small registry request, write the cache, exit. Failures are
+// silent by design — the notifier simply retries on a later invocation.
+const REGISTRY_LATEST = 'https://registry.npmjs.org/@hecer%2fyoke/latest';
+export async function refreshOnce(opts = {}) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await fetchFn(REGISTRY_LATEST, { signal: ctrl.signal });
+        if (!res.ok)
+            return;
+        const body = await res.json();
+        if (typeof body.version === 'string') {
+            writeCache({ checkedAt: (opts.now ?? new Date()).toISOString(), latest: body.version }, opts.cacheFile);
+        }
+    }
+    catch { /* offline / blocked / registry down — silent */ }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
+if (isMain) {
+    refreshOnce().then(() => process.exit(0));
+}

package/dist/update/upgrade.js

@@ -0,0 +1,30 @@
+import { execSync } from 'node:child_process';
+import { readCache, isNewer, currentYokeVersion } from './check.js';
+// `yoke upgrade` — the explicit path to the latest release.
+export function runUpgrade(opts = {}) {
+    const exec = opts.exec ?? ((cmd) => { execSync(cmd, { stdio: 'inherit' }); });
+    console.log('Upgrading @hecer/yoke to latest...');
+    try {
+        exec('npm install -g @hecer/yoke@latest');
+    }
+    catch (e) {
+        console.error(`Upgrade failed: ${e.message}`);
+        console.error('Running from a git clone? Upgrade with: git pull && npm install && npm run build');
+        return 1;
+    }
+    console.log('✓ upgraded — the new version is active on the next yoke invocation.');
+    return 0;
+}
+// Opt-in auto-upgrade (`update.auto: true` in .yoke/config.yaml), evaluated at
+// loop START only — never mid-run: the current process keeps executing the
+// version it started with; the upgrade takes effect on the next invocation.
+export function maybeAutoUpgrade(auto, opts = {}) {
+    if (auto !== true)
+        return;
+    const cache = readCache(opts.cacheFile);
+    const current = currentYokeVersion();
+    if (cache && isNewer(cache.latest, current)) {
+        console.error(`update.auto: upgrading yoke ${current} → ${cache.latest} (this run continues on ${current}; the upgrade applies from the next run)`);
+        runUpgrade(opts);
+    }
+}

package/docs/PUBLISHING.md

@@ -0,0 +1,41 @@
+# Publishing channels — status & playbook
+
+Where Yoke is published, and how each channel gets updated. (Researched 2026-07-10.)
+
+## Live
+
+| Channel | How | Update path |
+|---|---|---|
+| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | `npm publish` (2FA) | every release |
+| **GitHub** — [HECer/yoke](https://github.com/HECer/yoke) | push + tag | every release |
+| **Claude Code plugin (self-marketplace)** | `.claude-plugin/plugin.json` + `marketplace.json` in this repo; users: `/plugin marketplace add HECer/yoke` → `/plugin install yoke@yoke` | bump `version` in `plugin.json` |
+| **Gemini CLI extension** | `gemini-extension.json` + `GEMINI-EXTENSION.md` at repo root; users: `gemini extensions install https://github.com/HECer/yoke` | bump `version` in the manifest |
+
+## Submitted / pending
+
+| Channel | How | Status |
+|---|---|---|
+| **Gemini extensions gallery** (geminicli.com/extensions) | automatic daily crawl: needs `gemini-extension.json` at repo root + `gemini-cli-extension` repo topic — both done | wait for crawler |
+| **Anthropic community plugin directory** (`claude-community`, surfaced in `/plugin > Discover`) | form at **platform.claude.com/plugins/submit** (Console account, Developer role; submit the public repo URL; `claude plugin validate` runs in their pipeline — passes locally). After approval: pinned to a commit SHA, CI auto-bumps on push, catalog syncs nightly | **needs a human login** — see below |
+
+### Anthropic directory submission (manual step)
+
+1. Log in at https://platform.claude.com (free Console account is enough; role Developer+).
+2. Open https://platform.claude.com/plugins/submit
+3. Submit the public repo: `https://github.com/HECer/yoke`
+4. Suggested description: *"Cross-agent coding harness: one curated skill canon (TDD,
+   brainstorming → spec → plan, systematic debugging, cross-model review, design
+   verification) plus mechanical safety gates and an autonomous loop via the yoke CLI."*
+5. Category: development. Plugin name (immutable): `yoke`.
+
+## Worth doing later (community lists, PR/issue-based)
+
+- **awesome-claude-code** (hesreallyhim) — issue-form only, explicitly human-submitted, no PRs.
+- **ComposioHQ/awesome-claude-plugins** — PR per template (high merge latency).
+- **davila7/claude-code-templates** (aitmpl.com) — PR per CONTRIBUTING.md.
+- **Codex plugin directory** (platform.openai.com/plugins) — requires verified developer
+  identity + test cases; medium-high effort. Codex CLI users can already consume the repo
+  marketplace directly.
+- Auto-crawled directories (crossaitools.com etc.) pick the repo up on their own once the
+  marketplace manifest exists.
+- Launch channels (Product Hunt, Show HN, r/ClaudeAI, r/ClaudeCode) — deliberate, human-led.