@nema-project/nema 0.1.4 → 0.1.6

package/dist/extensions/install.js

@@ -0,0 +1,241 @@
+import {
+  parseSkillSource,
+  safeRepoPath
+} from "../chunks/chunk-W4DUBATU.js";
+
+// extensions/install.js
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { RAW, commitTree, encodePath, pinnedSkillRecord, resolveSkillSource } from "./source.js";
+var COMMIT = /^[0-9a-f]{40}$/;
+var MAX_FILES = 500;
+var MAX_FILE_BYTES = 5 * 1024 * 1024;
+var MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+var RESOLVE_TIMEOUT_MS = 45e3;
+var DOWNLOAD_TIMEOUT_MS = 10 * 6e4;
+var INTERRUPTED = "interrupted: the daemon stopped before the install finished";
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function gitBlobSha(bytes) {
+  return createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
+}
+function skillFiles(entries, folder) {
+  const prefix = folder === "." ? "" : `${folder}/`;
+  const inside = entries.filter((entry) => entry.path.startsWith(prefix) && entry.path !== folder);
+  const files = [];
+  for (const entry of inside) {
+    if (entry.type === "commit" || entry.mode === "160000")
+      throw new Error(`${entry.path} is a submodule`);
+    if (entry.type !== "blob")
+      continue;
+    if (entry.mode === "120000")
+      throw new Error(`${entry.path} is a symbolic link`);
+    const relative = entry.path.slice(prefix.length);
+    if (!safeRepoPath(relative))
+      throw new Error(`unsafe file name in ${entry.path}`);
+    files.push({ ...entry, relative });
+  }
+  if (files.length > MAX_FILES)
+    throw new Error(`${folder} has more than ${MAX_FILES} files`);
+  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const seen = /* @__PURE__ */ new Set();
+  let total = 0;
+  for (const file of files) {
+    const folded = file.relative.toLowerCase();
+    if (seen.has(folded))
+      throw new Error(`${file.path} differs from another file only in case`);
+    seen.add(folded);
+    if (file.size !== null && file.size > MAX_FILE_BYTES)
+      throw new Error(`${file.path} is larger than 5 MiB`);
+    total += file.size ?? 0;
+  }
+  if (total > MAX_TOTAL_BYTES)
+    throw new Error(`${folder} is larger than 20 MiB in total`);
+  return files;
+}
+var SkillInstaller = class {
+  o;
+  jobs = /* @__PURE__ */ new Map();
+  /** Ids a retry has claimed while it re-reads the recorded commit, before its job exists. */
+  reserved = /* @__PURE__ */ new Set();
+  staging;
+  constructor(o) {
+    this.o = o;
+    this.staging = path.join(o.root, "staging");
+  }
+  /** Called once at daemon start: no install can be running yet, so every `installing` record is left over. */
+  recover() {
+    rmSync(this.staging, { recursive: true, force: true });
+    mkdirSync(this.staging, { recursive: true });
+    const interrupted = this.o.store.list().filter((row) => row.provision === "managed" && row.installState === "installing").map((row) => row.id);
+    for (const id of interrupted)
+      this.o.store.failInstall(id, INTERRUPTED);
+    return interrupted;
+  }
+  /** True from the moment an install or retry is accepted until its cleanup has finished. */
+  running(id) {
+    return this.reserved.has(id) || this.jobs.get(id)?.active === true;
+  }
+  /** Called after a removal, so a finished job is not reported for an extension that is gone. */
+  forget(id) {
+    if (!this.running(id))
+      this.jobs.delete(id);
+  }
+  async start(request) {
+    return this.begin(request, null);
+  }
+  async begin(request, reservedFor) {
+    const { source, commit, path: folder } = request;
+    if (typeof source !== "string")
+      throw new Error("install needs a string source");
+    if (typeof commit !== "string" || !COMMIT.test(commit))
+      throw new Error("install needs a 40-character commit");
+    if (typeof folder !== "string" || folder !== "." && !safeRepoPath(folder))
+      throw new Error("invalid skill path");
+    const parsed = parseSkillSource(source);
+    const pinned = {
+      via: "github",
+      owner: parsed.owner,
+      repo: parsed.repo,
+      ref: commit,
+      path: folder === "." ? null : folder,
+      skill: null,
+      refPath: null,
+      exact: true
+    };
+    const resolution = await resolveSkillSource(pinned, { fetch: this.o.fetch, signal: AbortSignal.timeout(RESOLVE_TIMEOUT_MS) });
+    if (resolution.commit !== commit)
+      throw new Error(`${commit} resolved to a different commit`);
+    const pinnedRecord = pinnedSkillRecord(resolution, resolution.skills[0]);
+    if (reservedFor !== null && pinnedRecord.id !== reservedFor)
+      throw new Error(`${reservedFor} now resolves to a different skill (${pinnedRecord.id})`);
+    this.claim(pinnedRecord.id, reservedFor);
+    const previous = this.o.store.list().find((row) => row.id === pinnedRecord.id);
+    const record = previous ? { ...pinnedRecord, useState: previous.useState } : pinnedRecord;
+    this.o.store.putManaged(record);
+    return this.launch(record, resolution.owner, resolution.repo, commit, folder);
+  }
+  /** Start again from the commit and folder on the record, for a failed, cancelled or interrupted install. */
+  async retry(id) {
+    const record = this.o.store.list().find((row) => row.id === id);
+    if (!record || record.provision !== "managed" || !record.provenance)
+      throw new Error(`${id} has no install to retry`);
+    this.claim(id, null);
+    this.reserved.add(id);
+    try {
+      return await this.begin({ source: record.provenance.repository, commit: record.provenance.commit, path: record.provenance.path }, id);
+    } finally {
+      this.reserved.delete(id);
+    }
+  }
+  cancel(id) {
+    const job = this.jobs.get(id);
+    if (!job || job.state !== "running")
+      throw new Error(`${id} is not installing`);
+    job.controller.abort(new Error("cancelled"));
+    job.state = "cancelled";
+    return this.snapshot(job);
+  }
+  status(id) {
+    const record = this.o.store.list().find((row) => row.id === id);
+    const job = this.jobs.get(id);
+    if (job && (job.active || record))
+      return this.snapshot(job);
+    if (job)
+      this.jobs.delete(id);
+    if (!record || record.provision !== "managed")
+      throw new Error(`${id} has no install`);
+    const state = record.installState === "installed" ? "installed" : record.installState === "failed" ? "failed" : record.installState === "absent" ? "cancelled" : "running";
+    return { id, state, done: 0, total: 0, error: record.error, commit: record.provenance?.commit ?? null, path: record.provenance?.path ?? null };
+  }
+  /** Resolves once the current install of `id` has stopped, whichever way. For tests and shutdown. */
+  async settled(id) {
+    await this.jobs.get(id)?.promise;
+  }
+  /** One install per id at a time; an installed copy is not replaced (updating is its own operation). */
+  claim(id, reservedFor) {
+    if (reservedFor !== id && this.running(id))
+      throw new Error(`${id} is already being installed`);
+    const current = this.o.store.list().find((row) => row.id === id);
+    if (!current)
+      return;
+    if (current.provision !== "managed")
+      throw new Error(`${id} is taken by another extension`);
+    if (current.installState === "installed")
+      throw new Error(`${id} is already installed`);
+    if (current.installState === "installing")
+      throw new Error(`${id} is already being installed`);
+  }
+  snapshot(job) {
+    return { id: job.id, state: job.state, done: job.done, total: job.total, error: job.error, commit: job.commit, path: job.path };
+  }
+  launch(record, owner, repo, commit, folder) {
+    const controller = new AbortController();
+    const job = { id: record.id, state: "running", done: 0, total: 0, error: null, commit, path: folder, controller, promise: Promise.resolve(), active: true };
+    this.jobs.set(record.id, job);
+    job.promise = this.run(job, record, owner, repo, commit, folder);
+    return this.snapshot(job);
+  }
+  async run(job, record, owner, repo, commit, folder) {
+    const timeout = this.o.downloadTimeoutMs ?? DOWNLOAD_TIMEOUT_MS;
+    const signal = AbortSignal.any([job.controller.signal, AbortSignal.timeout(timeout)]);
+    let stage = null;
+    try {
+      mkdirSync(this.staging, { recursive: true });
+      stage = mkdtempSync(path.join(this.staging, `${record.id}-`));
+      const { entries, truncated } = await commitTree(owner, repo, commit, { fetch: this.o.fetch, signal });
+      if (truncated)
+        throw new Error(`GitHub cut the file list of ${owner}/${repo} short; it is too large to install from`);
+      const files = skillFiles(entries, folder);
+      job.total = files.length;
+      for (const file of files) {
+        const response = await this.o.fetch(`${RAW}/${owner}/${repo}/${commit}/${encodePath(file.path)}`, {
+          headers: { "User-Agent": "nema-extension-installer" },
+          signal
+        });
+        if (!response.ok)
+          throw new Error(`could not download ${file.path} (${response.status})`);
+        const bytes = Buffer.from(await response.arrayBuffer());
+        if (bytes.length > MAX_FILE_BYTES)
+          throw new Error(`${file.path} is larger than 5 MiB`);
+        if (gitBlobSha(bytes) !== file.sha)
+          throw new Error(`${file.path} does not match its Git blob hash`);
+        const target = path.resolve(stage, ...file.relative.split("/"));
+        if (!target.startsWith(stage + path.sep))
+          throw new Error(`unsafe file name in ${file.path}`);
+        mkdirSync(path.dirname(target), { recursive: true });
+        const mode = file.mode === "100755" ? 493 : 420;
+        writeFileSync(target, bytes, { flag: "wx", mode });
+        chmodSync(target, mode);
+        job.done += 1;
+      }
+      signal.throwIfAborted();
+      const current = this.o.store.list().find((row) => row.id === record.id);
+      this.o.store.installManaged({ ...record, useState: current?.useState ?? record.useState, installState: "installed", error: null }, stage);
+      job.state = "installed";
+    } catch (error) {
+      const cancelled = job.controller.signal.aborted;
+      const reason = cancelled ? null : error instanceof Error && error.name === "TimeoutError" ? `download did not finish within ${Math.round(timeout / 6e4)} min` : message(error);
+      job.state = cancelled ? "cancelled" : "failed";
+      job.error = reason;
+      try {
+        if (cancelled)
+          this.o.store.cancelInstall(record.id);
+        else
+          this.o.store.failInstall(record.id, reason);
+      } catch {
+      }
+    } finally {
+      if (stage)
+        rmSync(stage, { recursive: true, force: true });
+      job.active = false;
+    }
+  }
+};
+export {
+  INTERRUPTED,
+  SkillInstaller,
+  skillFiles
+};

package/dist/extensions/source.d.ts

@@ -0,0 +1,81 @@
+import { type ExtensionRecord, type SkillProblem, type SkillSource } from "@nema/shared";
+/**
+ * The slice of `fetch` the resolver needs. Production passes the global `fetch`; tests pass a fake
+ * GitHub, so no test depends on the network.
+ */
+export type SourceFetch = (url: string, init: {
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+export type { SkillProblem } from "@nema/shared";
+export type SkillCandidate = {
+    /** Managed id the skill would install under; null when it cannot be installed (see `problem`). */
+    id: string | null;
+    name: string;
+    description: string;
+    /** Folder of the skill inside the repository; `.` is the repository root. */
+    path: string;
+    /** Git blob SHA-1 of the SKILL.md at the pinned commit. */
+    digest: string;
+    problem: SkillProblem | null;
+};
+export type SkillResolution = {
+    repository: string;
+    owner: string;
+    repo: string;
+    /** The ref that was asked for: the link's ref, or the repository's default branch. */
+    ref: string;
+    /** What that ref pointed to when it was resolved. Every later read uses this, never the ref. */
+    commit: string;
+    /** SPDX id GitHub reports for the repository, or null when it reports none. */
+    license: string | null;
+    path: string | null;
+    skills: SkillCandidate[];
+    /** GitHub cut the tree listing short, so skills deeper in a very large repository may be missing. */
+    truncated: boolean;
+};
+export declare const RAW = "https://raw.githubusercontent.com";
+export type Options = {
+    fetch: SourceFetch;
+    signal?: AbortSignal;
+};
+export declare function encodePath(path: string): string;
+export type TreeEntry = {
+    path: string;
+    type: string;
+    mode: string;
+    sha: string;
+    size: number | null;
+};
+/** Every entry of a repository at one commit, as GitHub's recursive tree listing reports it. */
+export declare function commitTree(owner: string, repo: string, commit: string, o: Options): Promise<{
+    entries: TreeEntry[];
+    truncated: boolean;
+}>;
+/** `name` and `description` from a SKILL.md front matter; plain and folded/literal scalars only. */
+export declare function skillFrontMatter(text: string): {
+    name: string;
+    description: string;
+} | null;
+/**
+ * Resolve a parsed source to one commit and the skills it contains.
+ *
+ * The ref is read once, turned into a 40-character commit, and every later read (tree listing,
+ * SKILL.md contents) names that commit. A branch that moves while this runs, or between preview and
+ * install, cannot change what was previewed.
+ */
+export declare function resolveSkillSource(source: SkillSource, o: Options): Promise<SkillResolution>;
+/**
+ * The record a chosen skill is installed under. `revision` is the commit and `source` links to that
+ * commit, so the record keeps saying what was installed after the branch moves on.
+ */
+export declare function pinnedSkillRecord(resolution: SkillResolution, skill: SkillCandidate): ExtensionRecord;

package/dist/extensions/source.js

@@ -0,0 +1,203 @@
+import {
+  bundledExtensions
+} from "../chunks/chunk-W4DUBATU.js";
+
+// extensions/source.js
+var API = "https://api.github.com";
+var RAW = "https://raw.githubusercontent.com";
+var COMMIT = /^[0-9a-f]{40}$/;
+var ID = /^[a-z][a-z0-9-]{0,63}$/;
+var MAX_SKILLS = 50;
+var MAX_SCAN = 200;
+var MAX_SKILL_BYTES = 256 * 1024;
+var BUNDLED_IDS = new Set(bundledExtensions().map((row) => row.id));
+var HEADERS = { Accept: "application/vnd.github+json", "User-Agent": "nema-extension-resolver", "X-GitHub-Api-Version": "2022-11-28" };
+async function getJson(url, slug, o, notFound) {
+  const response = await o.fetch(url, { headers: HEADERS, signal: o.signal });
+  if (response.ok)
+    return response.json();
+  if ((response.status === 403 || response.status === 429) && response.headers.get("x-ratelimit-remaining") === "0") {
+    throw new Error("GitHub API rate limit reached; try again later");
+  }
+  if (response.status === 404 || response.status === 422)
+    throw new Error(notFound);
+  throw new Error(`GitHub returned ${response.status} for ${slug}`);
+}
+function field(value, key) {
+  return value && typeof value === "object" ? value[key] : void 0;
+}
+function scalar(value) {
+  const trimmed = value.trim();
+  const quote = trimmed[0];
+  if (quote === '"' || quote === "'") {
+    const end = trimmed.indexOf(quote, 1);
+    if (end > 0)
+      return trimmed.slice(1, end);
+  }
+  return trimmed.replace(/(^|\s+)#.*$/, "").trim();
+}
+function encodePath(path) {
+  return path.split("/").map(encodeURIComponent).join("/");
+}
+async function commitTree(owner, repo, commit, o) {
+  const slug = `${owner}/${repo}`;
+  const body = await getJson(`${API}/repos/${owner}/${repo}/git/trees/${commit}?recursive=1`, slug, o, `commit not found in ${slug}: ${commit}`);
+  const tree = field(body, "tree");
+  if (!Array.isArray(tree))
+    throw new Error(`GitHub returned no file list for ${slug} at ${commit}`);
+  const entries = tree.filter((entry) => typeof field(entry, "path") === "string" && typeof field(entry, "type") === "string" && typeof field(entry, "sha") === "string").map((entry) => ({
+    path: field(entry, "path"),
+    type: field(entry, "type"),
+    mode: typeof field(entry, "mode") === "string" ? field(entry, "mode") : "",
+    sha: field(entry, "sha"),
+    size: typeof field(entry, "size") === "number" ? field(entry, "size") : null
+  }));
+  return { entries, truncated: field(body, "truncated") === true };
+}
+function skillFrontMatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text.slice(0, 64 * 1024));
+  if (!match)
+    return null;
+  const lines = match[1].split(/\r?\n/);
+  const values = {};
+  for (let i = 0; i < lines.length; i++) {
+    const top = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i]);
+    if (!top)
+      continue;
+    const [, key, rest] = top;
+    if (rest === ">" || rest === "|" || rest === ">-" || rest === "|-") {
+      const block = [];
+      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1]))
+        block.push(lines[++i].trim());
+      values[key] = block.join(rest.startsWith(">") ? " " : "\n");
+    } else
+      values[key] = scalar(rest);
+  }
+  const name = values.name?.trim();
+  const description = values.description?.trim();
+  return name && description ? { name, description } : null;
+}
+function skillId(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+}
+async function resolveSkillSource(source, o) {
+  const slug = `${source.owner}/${source.repo}`;
+  const meta = await getJson(`${API}/repos/${source.owner}/${source.repo}`, slug, o, `GitHub repository not found: ${slug}`);
+  const fullName = field(meta, "full_name");
+  const [owner, repo] = typeof fullName === "string" && fullName.includes("/") ? fullName.split("/") : [source.owner, source.repo];
+  const defaultBranch = field(meta, "default_branch");
+  const ref = source.ref ?? (typeof defaultBranch === "string" && defaultBranch ? defaultBranch : null);
+  if (!ref)
+    throw new Error(`GitHub reported no default branch for ${slug}`);
+  const spdx = field(field(meta, "license"), "spdx_id");
+  const license = typeof spdx === "string" && spdx && spdx !== "NOASSERTION" ? spdx : null;
+  const segments = source.refPath ? source.refPath.split("/") : [];
+  const splits = segments.length ? segments.map((_, index) => ({ ref: segments.slice(0, index + 1).join("/"), path: segments.slice(index + 1).join("/") || null })) : [{ ref, path: source.path }];
+  let commit;
+  let chosenRef = ref;
+  let folderPath = source.path;
+  for (const split of splits) {
+    const notFound = `ref not found in ${slug}: ${ref}`;
+    try {
+      const body = await getJson(`${API}/repos/${source.owner}/${source.repo}/commits/${encodePath(split.ref)}`, slug, o, notFound);
+      commit = field(body, "sha");
+      chosenRef = split.ref;
+      folderPath = split.path;
+      break;
+    } catch (error) {
+      if (!(error instanceof Error && error.message === notFound) || split === splits.at(-1))
+        throw error;
+    }
+  }
+  if (typeof commit !== "string" || !COMMIT.test(commit))
+    throw new Error(`${chosenRef} in ${slug} did not resolve to a commit`);
+  const treeBody = await getJson(`${API}/repos/${source.owner}/${source.repo}/git/trees/${commit}?recursive=1`, slug, o, `commit not found in ${slug}: ${commit}`);
+  const tree = field(treeBody, "tree");
+  if (!Array.isArray(tree))
+    throw new Error(`GitHub returned no file list for ${slug} at ${commit}`);
+  const prefix = folderPath ? `${folderPath}/` : "";
+  const exactFile = `${prefix}SKILL.md`;
+  const files = tree.filter((entry) => typeof field(entry, "path") === "string" && field(entry, "type") === "blob" && typeof field(entry, "sha") === "string").filter((entry) => source.exact ? entry.path === exactFile : (entry.path === "SKILL.md" || entry.path.endsWith("/SKILL.md")) && entry.path.startsWith(prefix)).sort((a, b) => a.path.localeCompare(b.path));
+  if (files.length === 0)
+    throw new Error(`no SKILL.md under ${folderPath ?? "the repository root"} in ${slug} at ${commit}`);
+  const read = async (file) => {
+    const folder = file.path === "SKILL.md" ? "." : file.path.slice(0, -"/SKILL.md".length);
+    const fallback = folder === "." ? repo : folder.split("/").at(-1);
+    if (typeof file.size === "number" && file.size > MAX_SKILL_BYTES) {
+      return { id: null, name: fallback, description: "", path: folder, digest: file.sha, problem: "too-large" };
+    }
+    const response = await o.fetch(`${RAW}/${owner}/${repo}/${commit}/${encodePath(file.path)}`, { headers: { "User-Agent": HEADERS["User-Agent"] }, signal: o.signal });
+    if (!response.ok)
+      throw new Error(`could not read ${file.path} in ${slug} at ${commit} (${response.status})`);
+    const meta2 = skillFrontMatter(await response.text());
+    if (!meta2)
+      return { id: null, name: fallback, description: "", path: folder, digest: file.sha, problem: "missing-frontmatter" };
+    const id = skillId(meta2.name);
+    const problem = !ID.test(id) ? "invalid-id" : BUNDLED_IDS.has(id) ? "bundled-id" : null;
+    return { id: problem ? null : id, name: meta2.name, description: meta2.description, path: folder, digest: file.sha, problem };
+  };
+  let chosen = [];
+  const limit = source.skill ? MAX_SCAN : MAX_SKILLS;
+  for (const file of files.slice(0, limit))
+    chosen.push(await read(file));
+  if (source.skill) {
+    const wanted = source.skill;
+    const ranks = [
+      (skill) => skill.name === wanted,
+      (skill) => skill.id === wanted,
+      (skill) => skill.path.split("/").at(-1) === wanted
+    ];
+    const hits = ranks.map((rank) => chosen.filter(rank)).find((list) => list.length > 0) ?? [];
+    if (hits.length === 0)
+      throw new Error(`skill ${wanted} not found in ${slug} at ${commit}`);
+    if (hits.length > 1)
+      throw new Error(`skill ${wanted} is ambiguous in ${slug} at ${commit}: ${hits.map((skill) => skill.path).join(", ")}`);
+    chosen = hits;
+  }
+  const counts = /* @__PURE__ */ new Map();
+  for (const skill of chosen)
+    if (skill.id)
+      counts.set(skill.id, (counts.get(skill.id) ?? 0) + 1);
+  chosen = chosen.map((skill) => skill.id && counts.get(skill.id) > 1 ? { ...skill, id: null, problem: "duplicate-id" } : skill);
+  return {
+    repository: `https://github.com/${owner}/${repo}`,
+    owner,
+    repo,
+    ref: chosenRef,
+    commit,
+    license,
+    path: folderPath,
+    skills: chosen,
+    truncated: field(treeBody, "truncated") === true || files.length > limit
+  };
+}
+function pinnedSkillRecord(resolution, skill) {
+  if (!skill.id || skill.problem)
+    throw new Error(`skill ${skill.name} cannot be installed: ${skill.problem ?? "invalid-id"}`);
+  if (!COMMIT.test(resolution.commit))
+    throw new Error("a skill record needs a 40-character commit");
+  const folder = skill.path === "." ? "" : `/${encodePath(skill.path)}`;
+  return {
+    id: skill.id,
+    kind: "skill",
+    name: skill.name,
+    summary: skill.description,
+    source: `${resolution.repository}/tree/${resolution.commit}${folder}`,
+    revision: resolution.commit,
+    provision: "managed",
+    installState: "installing",
+    useState: "enabled",
+    availability: "ready",
+    externalPath: null,
+    error: null,
+    provenance: { repository: resolution.repository, commit: resolution.commit, path: skill.path, digest: skill.digest, license: resolution.license }
+  };
+}
+export {
+  RAW,
+  commitTree,
+  encodePath,
+  pinnedSkillRecord,
+  resolveSkillSource,
+  skillFrontMatter
+};

package/dist/extensions/store.d.ts

@@ -7,5 +7,12 @@ export declare function openExtensionStore(root: string): {
     removeManaged(id: string): void;
     detach(id: string): void;
     installManaged(record: ExtensionRecord, stagedDir: string): void;
+    /**
+     * Flip the use state of a record. Bundled extensions live in `bundledExtensions()`, so their
+     * choice is stored as an override row rather than by editing the seed.
+     */
+    setUseState(id: string, useState: ExtensionRecord["useState"]): ExtensionRecord;
+    /** End an install that did not finish: drop whatever reached the managed folder and keep the reason. */
+    failInstall(id: string, error: string): void;
     cancelInstall(id: string): void;
 };

package/dist/extensions/store.js

@@ -1,9 +1,9 @@
 import {
   bundledExtensions
-} from "../chunks/chunk-HEIQINX3.js";
+} from "../chunks/chunk-W4DUBATU.js";
 
 // extensions/store.js
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeSync } from "node:fs";
 import path from "node:path";
 var ID = /^[a-z][a-z0-9-]{0,63}$/;
 var BUNDLED_IDS = new Set(bundledExtensions().map((row) => row.id));
@@ -11,6 +11,17 @@ function assertId(id) {
   if (!ID.test(id) || BUNDLED_IDS.has(id))
     throw new Error(`invalid extension id: ${id}`);
 }
+var COMMIT = /^[0-9a-f]{40}$/;
+function assertPinned(record) {
+  if (record.provision !== "managed")
+    return;
+  if (!/^https:\/\/(www\.)?github\.com\//i.test(record.source))
+    return;
+  const linked = /^https:\/\/(?:www\.)?github\.com\/[^/]+\/[^/]+\/tree\/([0-9a-f]{40})(?:\/|$)/i.exec(record.source)?.[1];
+  if (!COMMIT.test(record.revision) || linked !== record.revision) {
+    throw new Error("a GitHub source must be pinned to a 40-character commit");
+  }
+}
 function indexPath(root) {
   return path.join(root, "index.json");
 }
@@ -25,7 +36,21 @@ function readExtra(root) {
 }
 function writeExtra(root, rows) {
   mkdirSync(root, { recursive: true });
-  writeFileSync(indexPath(root), JSON.stringify(rows));
+  const target = indexPath(root);
+  const temp = path.join(root, `index.json.${process.pid}.${Date.now()}.tmp`);
+  const fd = openSync(temp, "w", 384);
+  try {
+    writeSync(fd, JSON.stringify(rows));
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    renameSync(temp, target);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
 }
 function managedPath(root, id) {
   const extensions = path.resolve(root, "extensions");
@@ -37,6 +62,8 @@ function managedPath(root, id) {
 function ownedDirectory(root, id) {
   const { extensions, target } = managedPath(root, id);
   mkdirSync(extensions, { recursive: true });
+  if (lstatSync(extensions).isSymbolicLink())
+    throw new Error("managed extensions root is a symbolic link");
   const realExtensions = realpathSync(extensions);
   if (!existsSync(target))
     return target;
@@ -51,11 +78,17 @@ function ownedDirectory(root, id) {
 function openExtensionStore(root) {
   return {
     list() {
-      const extra = readExtra(root).filter((row) => !BUNDLED_IDS.has(row.id));
-      return [...bundledExtensions(), ...extra];
+      const rows = readExtra(root);
+      const overrides = new Map(rows.filter((row) => BUNDLED_IDS.has(row.id)).map((row) => [row.id, row]));
+      const seeds = bundledExtensions().map((row) => {
+        const override = overrides.get(row.id);
+        return override ? { ...row, useState: override.useState } : row;
+      });
+      return [...seeds, ...rows.filter((row) => !BUNDLED_IDS.has(row.id))];
     },
     putManaged(record) {
       assertId(record.id);
+      assertPinned(record);
       if (record.provision === "managed") {
         const target = ownedDirectory(root, record.id);
         if (!existsSync(target))
@@ -92,6 +125,7 @@ function openExtensionStore(root) {
       assertId(record.id);
       if (record.provision !== "managed")
         throw new Error("only a managed extension can be installed");
+      assertPinned(record);
       if (!existsSync(stagedDir) || !lstatSync(stagedDir).isDirectory()) {
         throw new Error("staged extension directory is missing");
       }
@@ -114,6 +148,39 @@ function openExtensionStore(root) {
       rows.push({ ...record, provision: "managed", installState: "installed", error: null });
       writeExtra(root, rows);
     },
+    /**
+     * Flip the use state of a record. Bundled extensions live in `bundledExtensions()`, so their
+     * choice is stored as an override row rather than by editing the seed.
+     */
+    setUseState(id, useState) {
+      if (useState !== "enabled" && useState !== "disabled")
+        throw new Error(`invalid use state: ${useState}`);
+      if (BUNDLED_IDS.has(id)) {
+        const rows = readExtra(root).filter((row) => row.id !== id);
+        const seed = bundledExtensions().find((row) => row.id === id);
+        rows.push({ ...seed, useState });
+        writeExtra(root, rows);
+        return { ...seed, useState };
+      }
+      const current = readExtra(root).find((row) => row.id === id);
+      if (!current)
+        throw new Error("extension is not installed here");
+      const next = { ...current, useState };
+      writeExtra(root, readExtra(root).map((row) => row.id === id ? next : row));
+      return next;
+    },
+    /** End an install that did not finish: drop whatever reached the managed folder and keep the reason. */
+    failInstall(id, error) {
+      assertId(id);
+      const current = readExtra(root).find((row) => row.id === id);
+      if (!current || current.provision !== "managed" || current.installState !== "installing")
+        throw new Error("extension is not installing");
+      const target = ownedDirectory(root, id);
+      if (existsSync(target))
+        rmSync(target, { recursive: true, force: true });
+      rmSync(path.join(managedPath(root, id).extensions, `.${id}.incoming`), { recursive: true, force: true });
+      writeExtra(root, readExtra(root).map((row) => row.id === id ? { ...row, installState: "failed", error } : row));
+    },
     cancelInstall(id) {
       assertId(id);
       const current = readExtra(root).find((row) => row.id === id);

package/dist/github/client.js

@@ -4,7 +4,7 @@ import {
 import {
   GH_COMMAND_TOOLS,
   PLUGINS
-} from "../chunks/chunk-HEIQINX3.js";
+} from "../chunks/chunk-W4DUBATU.js";
 
 // github/client.js
 import { execFile, spawn } from "node:child_process";