rigline 1.0.0-alpha.1 → 1.0.0-alpha.10

package/README.md

@@ -1,18 +1,29 @@
 # rigline
 
-The command-line surface for [Rigline](https://github.com/Rigline/Rigline), a plugin layer for the
-Claude Code VS Code extension.
+The command for [Rigline](https://github.com/Rigline/Rigline), a plugin layer for the Claude Code
+VS Code extension.
 
 Rigline injects a small loader into the installed extension's webview, gives plugins a
 capability-scoped context to write against, and harvests the identifiers those plugins depend on
 from whichever extension version you have installed — so an extension update is a diff to read
 rather than a breakage to chase.
 
+**This modifies files belonging to Anthropic's extension, on your machine, and that is your call to
+make.** [Anthropic compliance](https://github.com/Rigline/Rigline/blob/main/docs/anthropic-compliance.md)
+is a straight account of what Rigline does and does not do — no credentials, no network calls, no
+rerouting of Claude usage, no redistribution — and how we read Anthropic's terms. `rigline restore`
+puts every install back to Anthropic's own bytes and needs nothing but Node.
+
 ## Install
 
     npm install -g rigline
     rigline install
 
+The first command you run fetches the engine, [`@rigline/core`](https://www.npmjs.com/package/@rigline/core),
+into `~/.rigline/engine` and runs it from there. It takes a few seconds and needs the registry;
+after that nothing reaches the network unless you ask it to. If that directory is ever in a bad
+state, delete it and run any command again.
+
 `install` finds every installed version of the extension, harvests it, bakes the discovered plugins
 into a payload and injects the loader. It keeps a byte-faithful backup of each bundle it touches,
 and `rigline restore` puts everything back using nothing but Node and the backup.
@@ -21,6 +32,25 @@ The extension updates about weekly and an update installs a fresh directory, whi
 the injection. Run `install` again afterwards; a window that is already open keeps running the old
 directory until *Developer: Reload Window*.
 
+**That is the whole of Rigline, and it needs nothing else.** Everything below is optional.
+
+## Optional: let an extension do the remembering
+
+    rigline vscode-setup
+
+If running `install` after every update is a chore, this installs a companion extension that does it
+for you — into every VS Code found on your `PATH`, Insiders, VSCodium, Cursor and Windsurf included,
+from a VSIX that ships inside the engine. Nothing is downloaded, and the companion moves when the
+engine does. It injects as it goes, so it is a step *instead of* `install` rather than after it.
+
+From then on it watches for the extension update and re-injects behind it, so there is nothing to
+remember after one.
+
+**Decline it and lose nothing.** `install` remains complete on its own, and is the right answer if
+you would rather not add an extension, cannot install one, or simply prefer running the thing
+yourself. `rigline vscode-setup --remove` goes back to that — it takes the companion out and leaves
+your injection alone, and `rigline restore` is what undoes the injection itself.
+
 ## Commands
 
     rigline install    inject every version, bake plugins, report drift, record the baseline
@@ -30,8 +60,10 @@ directory until *Developer: Reload Window*.
 
     rigline add SPEC   install a plugin from a directory or npm, and re-inject
     rigline remove N   delete a plugin rigline installed, and re-inject
-    rigline update     move each npm plugin to what its tag resolves to
-    rigline list       every plugin, in load order: origin, source, switch, what it can do
+    rigline disable N  switch a plugin off, and re-inject
+    rigline enable N   switch it back on, and re-inject
+    rigline update     move the engine and every npm plugin to what its tag resolves to
+    rigline list       every plugin, in load order: version, origin, source, switch, what it can do
 
     rigline build      build a plugin to one browser ES module
     rigline dev        rebuild and re-inject as you edit
@@ -39,9 +71,25 @@ directory until *Developer: Reload Window*.
     rigline diff A B   identifier drift between two extension directories
     rigline doctor     install state per version, as a pasteable report
 
-`add` never runs a package manager: a published plugin is one bundled ES module and a manifest, so
-there is nothing to resolve. A version must reach a minimum age (a day, by default) before `add` or
-`update` will take it, and a withheld version is named rather than skipped in silence.
+    rigline --version  this command's version and the installed engine's
+    rigline --help     the whole surface, from the engine
+
+`add` never runs a package manager for a plugin: a published plugin is one bundled ES module and a
+manifest, so there is nothing to resolve. A version must reach a minimum age (a day, by default)
+before `add` or `update` will take it, and a withheld version is named rather than skipped in
+silence. `update` applies the same rule to the engine, and says which version it moved from so
+going back is one command.
+
+## How it is put together
+
+`rigline` is a small retrieval layer. It fetches bytes — a plugin tarball, the engine — checks them,
+and hands them over; `@rigline/core` does everything else and answers every verb above. The split is
+not decoration: a process cannot replace the package it is running out of, so whatever performs an
+update has to sit above the thing being updated.
+
+**It belongs in no project's dependencies.** If you are writing plugins, your workspace declares
+`@rigline/core` and runs `rigline-engine`; `npm create rigline-plugin` scaffolds it that way. A
+project that can declare dependencies does not need a delivery mechanism.
 
 ## Writing a plugin
 
@@ -51,4 +99,7 @@ there is nothing to resolve. A version must reach a minimum age (a day, by defau
 form. [Anchors](https://github.com/Rigline/Rigline/blob/main/docs/anchors.md) is what to read when
 an extension update breaks a plugin and you would rather not wait for a release.
 
+[Changelog](https://github.com/Rigline/Rigline/blob/main/CHANGELOG.md) — every package in this
+workspace shares it, and one version number.
+
 MIT.

package/dist/engine.js

@@ -0,0 +1,241 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { UserError } from "./errors.js";
+import { withHomeLock } from "./lock.js";
+import { releaseAgeProblem, resolveVersion } from "./registry.js";
+export const ENGINE_PACKAGE = "@rigline/core";
+export const ENGINE_BIN = "rigline-engine";
+export function riglineHome(env = process.env) {
+    const override = env.RIGLINE_HOME;
+    return override && override.length > 0 ? override : join(homedir(), ".rigline");
+}
+export function engineDir(home = riglineHome()) {
+    return join(home, "engine");
+}
+export function wrapperVersion() {
+    const manifest = fileURLToPath(new URL("../package.json", import.meta.url));
+    const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+    const version = parsed.version;
+    if (typeof version !== "string")
+        throw new Error(`${manifest} has no version`);
+    return version;
+}
+export function majorOf(version) {
+    const match = /^(\d+)\./.exec(version);
+    return match === null ? null : Number(match[1]);
+}
+export function readEngineState(prefix) {
+    const dir = join(prefix, "node_modules", ENGINE_PACKAGE);
+    const manifest = join(dir, "package.json");
+    if (!existsSync(manifest))
+        return { kind: "none" };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifest, "utf8"));
+    }
+    catch {
+        return { kind: "unusable", version: "unreadable", why: `${manifest} is not readable JSON` };
+    }
+    const version = typeof parsed.version === "string" ? parsed.version : "unreadable";
+    const bin = parsed.bin;
+    const named = typeof bin === "object" && bin !== null
+        ? bin[ENGINE_BIN]
+        : undefined;
+    if (typeof named !== "string") {
+        return { kind: "unusable", version, why: `it has no ${ENGINE_BIN} command` };
+    }
+    const entry = resolve(dir, named);
+    if (!existsSync(entry)) {
+        return { kind: "unusable", version, why: `its ${ENGINE_BIN} entry ${entry} is missing` };
+    }
+    return { kind: "ready", version, entry };
+}
+export function majorProblem(wrapper, engine) {
+    const ours = majorOf(wrapper);
+    const theirs = majorOf(engine);
+    if (ours === null || theirs === null || ours === theirs)
+        return null;
+    return (`rigline ${ours}.x cannot run engine ${theirs}.x (${ENGINE_PACKAGE} ${engine}). ` +
+        "Run npm i -g rigline@latest.");
+}
+export function findNpmCli(execPath = process.execPath, exists = existsSync) {
+    const here = dirname(execPath);
+    const candidates = [
+        join(here, "node_modules", "npm", "bin", "npm-cli.js"),
+        join(here, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+    ];
+    const found = candidates.find(exists);
+    if (found === undefined) {
+        throw new UserError(`no npm was found beside ${execPath}, so the engine cannot be installed. ` +
+            `Run: npm install --prefix ${engineDir()} --save-exact --ignore-scripts ${ENGINE_PACKAGE}@latest`);
+    }
+    return found;
+}
+export function engineInstallArgv(options) {
+    return [
+        options.npmCli,
+        "install",
+        "--prefix",
+        options.prefix,
+        "--save-exact",
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+        "--loglevel=error",
+        ...options.specs,
+    ];
+}
+const nodeSpawn = (command, args, options) => spawn(command, [...args], { stdio: [...options.stdio] });
+export async function ensureEngine(options = {}) {
+    const prefix = engineDir(options.home ?? riglineHome());
+    const version = options.version ?? wrapperVersion();
+    const state = readEngineState(prefix);
+    if (state.kind === "ready") {
+        const problem = majorProblem(version, state.version);
+        if (problem !== null)
+            throw new UserError(problem);
+        return engineAt(state, options);
+    }
+    const resolved = await resolveEngine(options);
+    if (state.kind === "unusable" && resolved.version === state.version) {
+        throw new UserError(`the engine in ${prefix} is ${ENGINE_PACKAGE} ${state.version} and ${state.why}, ` +
+            `and that is what ${ENGINE_PACKAGE}@${options.tag ?? "latest"} resolves to. ` +
+            `Delete ${prefix} and try again, or install a version that has one.`);
+    }
+    const problem = majorProblem(version, resolved.version);
+    if (problem !== null)
+        throw new UserError(problem);
+    console.log(`rigline: installing the engine, ${ENGINE_PACKAGE} ${resolved.version}`);
+    await installEngine(prefix, `${ENGINE_PACKAGE}@${resolved.version}`, options);
+    const installed = readEngineState(prefix);
+    if (installed.kind !== "ready") {
+        throw new UserError(`${ENGINE_PACKAGE} ${resolved.version} was installed into ${prefix}, but ` +
+            (installed.kind === "unusable" ? installed.why : "nothing is there"));
+    }
+    return engineAt(installed, options);
+}
+async function resolveEngine(options) {
+    return await resolveVersion({ name: ENGINE_PACKAGE, version: null, tag: options.tag ?? "latest" }, options.registry);
+}
+async function installEngine(prefix, spec, options) {
+    const home = options.home ?? riglineHome();
+    await withHomeLock({ home, what: options.label ?? "rigline", ...options.lock }, async () => {
+        mkdirSync(prefix, { recursive: true });
+        const node = options.nodePath ?? process.execPath;
+        const argv = engineInstallArgv({ npmCli: findNpmCli(node), prefix, specs: [spec] });
+        const run = await capture(node, argv, options.spawnImpl);
+        if (run.code !== 0) {
+            throw new UserError(`installing ${spec} into ${prefix} failed (npm exited ${run.code}).\n${run.output.trim()}`);
+        }
+    });
+}
+function engineAt(state, options) {
+    const spawnImpl = options.spawnImpl ?? nodeSpawn;
+    const node = options.nodePath ?? process.execPath;
+    return {
+        version: state.version,
+        entry: state.entry,
+        run: (argv) => new Promise((done, fail) => {
+            const child = spawnImpl(node, [state.entry, ...argv], {
+                stdio: ["inherit", "inherit", "inherit"],
+            });
+            child.on("error", fail);
+            child.on("close", (code) => done(code ?? 1));
+        }),
+        json: async (argv) => {
+            const run = await capture(node, [state.entry, ...argv], spawnImpl, "inherit");
+            if (run.code !== 0) {
+                throw new UserError(`the engine exited ${run.code} for \`${argv.join(" ")}\``);
+            }
+            try {
+                return JSON.parse(run.output);
+            }
+            catch {
+                throw new UserError(`the engine answered \`${argv.join(" ")}\` with something that is not JSON`);
+            }
+        },
+    };
+}
+async function capture(command, argv, spawnImpl = nodeSpawn, stderr = "pipe") {
+    return await new Promise((done, fail) => {
+        const child = spawnImpl(command, argv, { stdio: ["ignore", "pipe", stderr] });
+        let output = "";
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            output += chunk;
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            output += chunk;
+        });
+        child.on("error", fail);
+        child.on("close", (code) => done({ code: code ?? 1, output }));
+    });
+}
+export async function updateEngine(options = {}) {
+    const prefix = engineDir(options.home ?? riglineHome());
+    const state = readEngineState(prefix);
+    const installed = state.kind === "none" ? null : state.version;
+    let resolved;
+    try {
+        resolved = await resolveEngine(options);
+    }
+    catch (error) {
+        return {
+            outcome: "failed",
+            ...(installed === null ? {} : { from: installed }),
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (state.kind === "ready" && resolved.version === state.version) {
+        return { outcome: "current", from: state.version };
+    }
+    const problem = majorProblem(options.version ?? wrapperVersion(), resolved.version);
+    if (problem !== null) {
+        return {
+            outcome: "failed",
+            ...(installed === null ? {} : { from: installed }),
+            reason: problem,
+        };
+    }
+    if (installed !== null) {
+        const withheld = releaseAgeProblem(resolved, options.registry);
+        if (withheld !== null) {
+            return { outcome: "withheld", from: installed, to: resolved.version, reason: withheld };
+        }
+    }
+    try {
+        await installEngine(prefix, `${ENGINE_PACKAGE}@${resolved.version}`, options);
+    }
+    catch (error) {
+        return {
+            outcome: "failed",
+            ...(installed === null ? {} : { from: installed }),
+            to: resolved.version,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return installed === null
+        ? { outcome: "installed", to: resolved.version }
+        : { outcome: "moved", from: installed, to: resolved.version };
+}
+export function formatEngineUpdate(update, home = riglineHome()) {
+    switch (update.outcome) {
+        case "installed":
+            return `engine: installed ${update.to}`;
+        case "moved":
+            return (`engine: ${update.from} -> ${update.to}\n` +
+                `  to go back: npm install --prefix ${engineDir(home)} --save-exact ` +
+                `${ENGINE_PACKAGE}@${update.from}`);
+        case "current":
+            return `engine: ${update.from}, which is what its tag resolves to`;
+        case "withheld":
+            return `engine: staying on ${update.from} — ${update.reason}`;
+        default:
+            return `engine: FAILED — ${update.reason}`;
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/errors.js

@@ -0,0 +1,4 @@
+export class UserError extends Error {
+    name = "UserError";
+}
+//# sourceMappingURL=errors.js.map