knowingdog 0.0.0-stage → 0.2.0

package/knowing-skills.mjs

@@ -0,0 +1,1058 @@
+#!/usr/bin/env node
+import { createHash, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  mkdir,
+  readFile,
+  writeFile,
+  lstat,
+  realpath,
+  rename,
+  rm,
+} from "node:fs/promises";
+import { setTimeout as wait } from "node:timers/promises";
+import { execFile } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { promisify } from "node:util";
+const runFile = promisify(execFile);
+const print = (value) => process.stdout.write(`${value}\n`);
+
+export function siteOrigin(value) {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.pathname !== "/" ||
+    url.search ||
+    url.hash ||
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw new Error(
+      "Use an HTTPS site origin, or HTTP localhost for development.",
+    );
+  return url.origin;
+}
+export function checksum(files) {
+  return createHash("sha256")
+    .update(
+      JSON.stringify(
+        [...files].sort((a, b) =>
+          a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+        ),
+      ),
+    )
+    .digest("hex");
+}
+export function validateArtifact(artifact, expected) {
+  if (
+    !artifact ||
+    artifact.identifier !== expected.identifier ||
+    (expected.version && artifact.version !== expected.version) ||
+    artifact.format !== expected.format ||
+    !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?(?:\+[a-zA-Z0-9.-]+)?$/.test(
+      artifact.version,
+    ) ||
+    !Array.isArray(artifact.files) ||
+    !artifact.files.length ||
+    artifact.files.length > 1006
+  )
+    throw new Error("Unexpected release response.");
+  const seen = new Set();
+  let bytes = 0;
+  for (const file of artifact.files) {
+    if (
+      typeof file.path !== "string" ||
+      typeof file.content !== "string" ||
+      !/^(skills\/[a-z0-9-]+\/[a-zA-Z0-9_./-]+|README\.md|\.mcp\.json|\.(?:codex|claude)-plugin\/(?:plugin|marketplace)\.json|\.agents\/plugins\/marketplace\.json)$/.test(
+        file.path,
+      ) ||
+      file.path
+        .split("/")
+        .some((part) => !part || part === "." || part === "..") ||
+      seen.has(file.path.toLowerCase())
+    )
+      throw new Error("Unsafe artifact path.");
+    seen.add(file.path.toLowerCase());
+    if (
+      file.encoding !== undefined &&
+      (file.encoding !== "base64" ||
+        !/\.(?:png|jpe?g|webp|gif)$/i.test(file.path) ||
+        Buffer.from(file.content, "base64").toString("base64") !== file.content)
+    )
+      throw new Error("Invalid binary reference.");
+    const fileBytes = file.encoding
+      ? Buffer.from(file.content, "base64").length
+      : Buffer.byteLength(file.content);
+    bytes += fileBytes;
+    if (fileBytes > 500000 || bytes > 12500000 || file.content.includes("\0"))
+      throw new Error("Artifact exceeds text-file limits.");
+    if (expected.skill && !file.path.startsWith(`skills/${expected.skill}/`))
+      throw new Error("Unexpected file outside the selected skill.");
+    if (
+      file.path.startsWith(".") &&
+      !(
+        file.path === ".mcp.json" &&
+        ["codex-plugin", "claude-plugin"].includes(expected.format)
+      ) &&
+      !(
+        expected.format === "codex-plugin" &&
+        file.path === ".agents/plugins/marketplace.json"
+      ) &&
+      !file.path.startsWith(
+        expected.format === "codex-plugin"
+          ? ".codex-plugin/"
+          : expected.format === "claude-plugin"
+            ? ".claude-plugin/"
+            : "never/",
+      )
+    )
+      throw new Error("Unexpected plugin manifest.");
+  }
+  if (expected.format === "codex-plugin") {
+    const catalog = JSON.parse(
+      artifact.files.find(
+        (file) => file.path === ".agents/plugins/marketplace.json",
+      )?.content ?? "null",
+    );
+    const entry = catalog?.plugins?.[0];
+    if (
+      !catalog ||
+      !/^[a-z0-9-]+$/.test(catalog.name) ||
+      catalog.plugins?.length !== 1 ||
+      entry?.name !==
+        JSON.parse(
+          artifact.files.find(
+            (file) => file.path === ".codex-plugin/plugin.json",
+          )?.content ?? "null",
+        )?.name ||
+      entry.source?.source !== "local" ||
+      entry.source?.path !== "./"
+    )
+      throw new Error("Unexpected Codex marketplace catalog.");
+  }
+  if (expected.format === "claude-plugin") {
+    const marketplace = artifact.files.find(
+      (file) => file.path === ".claude-plugin/marketplace.json",
+    );
+    if (marketplace) {
+      const catalog = JSON.parse(marketplace.content);
+      const plugin = JSON.parse(
+        artifact.files.find(
+          (file) => file.path === ".claude-plugin/plugin.json",
+        )?.content ?? "null",
+      );
+      if (
+        !/^[a-z0-9-]+$/.test(catalog.name) ||
+        typeof catalog.owner?.name !== "string" ||
+        catalog.plugins?.length !== 1 ||
+        catalog.plugins[0].name !== plugin?.name ||
+        catalog.plugins[0].source !== "./"
+      )
+        throw new Error("Unexpected Claude marketplace catalog.");
+    }
+  }
+  if (checksum(artifact.files) !== artifact.checksum)
+    throw new Error("Release checksum mismatch.");
+  return artifact;
+}
+async function safeDirectory(directory) {
+  const parsed = path.parse(path.resolve(directory));
+  let current = parsed.root;
+  for (const part of path
+    .resolve(directory)
+    .slice(parsed.root.length)
+    .split(path.sep)) {
+    if (!part) continue;
+    current = path.join(current, part);
+    try {
+      await mkdir(current);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    const stat = await lstat(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+      throw new Error(`Unsafe directory: ${current}`);
+  }
+}
+export async function installArtifact(artifact, options = {}) {
+  const cwd = await realpath(path.resolve(options.cwd ?? process.cwd()));
+  const created = [];
+  try {
+    if (["skills", "space-skill"].includes(artifact.format)) {
+      const base = path.join(
+        cwd,
+        options.agent === "claude" ? ".claude" : ".agents",
+        "skills",
+      );
+      await safeDirectory(base);
+      const names = [
+        ...new Set(
+          artifact.files
+            .filter((f) => f.path.startsWith("skills/"))
+            .map((f) => f.path.split("/")[1]),
+        ),
+      ];
+      if (!names.length) throw new Error("The release contains no skills.");
+      for (const name of names) {
+        const dest = path.join(base, name);
+        await mkdir(dest);
+        created.push(dest);
+      }
+      for (const file of artifact.files.filter((f) =>
+        f.path.startsWith("skills/"),
+      )) {
+        const dest = path.join(base, file.path.slice(7));
+        await safeDirectory(path.dirname(dest));
+        await writeFile(
+          dest,
+          file.encoding ? Buffer.from(file.content, "base64") : file.content,
+          { flag: "wx", mode: 0o644 },
+        );
+      }
+    } else {
+      const base = path.join(
+        cwd,
+        ".knowing",
+        "plugins",
+        artifact.identifier.replace("/", "--"),
+        artifact.version,
+      );
+      await safeDirectory(base);
+      const dest = path.join(base, artifact.format);
+      await mkdir(dest);
+      created.push(dest);
+      for (const file of artifact.files) {
+        const output = path.join(dest, file.path);
+        await safeDirectory(path.dirname(output));
+        await writeFile(
+          output,
+          file.encoding ? Buffer.from(file.content, "base64") : file.content,
+          { flag: "wx", mode: 0o644 },
+        );
+      }
+    }
+    return created;
+  } catch (error) {
+    for (const directory of created.reverse())
+      await rm(directory, { recursive: true, force: true });
+    if (error.code === "EEXIST")
+      throw new Error(
+        "A destination already exists. Existing files were preserved; choose another project or remove the old installation yourself.",
+      );
+    throw error;
+  }
+}
+async function rpc(origin, procedure, input, mutation, token) {
+  const url = new URL(`/api/trpc/knowing.skills.${procedure}`, origin);
+  const payload = JSON.stringify({ json: input });
+  if (!mutation) url.searchParams.set("input", payload);
+  const response = await fetch(url, {
+    method: mutation ? "POST" : "GET",
+    redirect: "error",
+    signal: AbortSignal.timeout(120000),
+    headers: {
+      ...(mutation ? { "Content-Type": "application/json" } : {}),
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    ...(mutation ? { body: payload } : {}),
+  });
+  const text = await response.text();
+  if (text.length > 25000000) throw new Error("Release response is too large.");
+  const data = JSON.parse(text);
+  if (
+    token &&
+    !process.env.KNOWING_INSTALL_TOKEN &&
+    !mutation &&
+    ["resolve", "artifact", "installAccess"].includes(procedure) &&
+    data.error?.json?.data?.code === "UNAUTHORIZED"
+  )
+    return rpc(origin, procedure, input, false);
+  if (!response.ok || data.error)
+    throw Object.assign(
+      new Error(data.error?.json?.message ?? "Knowing request failed."),
+      { code: data.error?.json?.data?.code },
+    );
+  return data.result.data.json;
+}
+async function configurationDirectory(value) {
+  if (!value) return undefined;
+  let current = path.resolve(value);
+  const missing = [];
+  for (;;) {
+    try {
+      return path.join(await realpath(current), ...missing);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      missing.unshift(path.basename(current));
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      current = parent;
+    }
+  }
+}
+function credentialsFile(origin, configDir) {
+  return path.join(
+    configDir
+      ? path.resolve(configDir)
+      : path.join(homedir(), ".config", "knowing-skills"),
+    createHash("sha256").update(origin).digest("hex") + ".json",
+  );
+}
+export async function saveConfiguration(file, value) {
+  await safeDirectory(path.dirname(file));
+  const temporary = `${file}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(value), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+async function credentials(origin, configDir) {
+  try {
+    return JSON.parse(
+      await readFile(credentialsFile(origin, configDir), "utf8"),
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function openBrowser(url) {
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "rundll32"
+        : "xdg-open";
+  execFile(
+    command,
+    process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url],
+    (error) => {
+      // stderr, so `login --install-only | gh secret set` receives only the token.
+      if (error)
+        process.stderr.write(
+          "Open the URL above in your browser to continue.\n",
+        );
+    },
+  );
+}
+export function releaseTarget(value, configuredOrigin) {
+  if (/^https?:\/\//.test(value ?? "")) {
+    const url = new URL(value);
+    const slug = /^\/s\/([^/]+)\/?$/.exec(url.pathname)?.[1];
+    if (!slug || url.search || url.hash || url.username || url.password)
+      throw new Error(
+        "Use the space's root URL, without a page, query or fragment.",
+      );
+    return {
+      origin: siteOrigin(url.origin),
+      input: { slug: decodeURIComponent(slug) },
+    };
+  }
+  if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(value ?? ""))
+    throw new Error("Provide a space URL or owner/repository.");
+  if (!configuredOrigin)
+    throw new Error(
+      "Use a space URL for your first install, or set --site / KNOWING_SITE. Login remembers the site for later owner/repository commands.",
+    );
+  return { origin: siteOrigin(configuredOrigin), input: { identifier: value } };
+}
+export function releaseSetup(command, release, options = {}) {
+  if (options.free && options.premium)
+    throw new Error("Choose --free or --premium.");
+  const method = command === "add-agent" ? "agent" : "github";
+  if (
+    (options.premium && !release.fullAccess) ||
+    (!options.free && command !== "add-skill" && release.requiresAccess[method])
+  ) {
+    // Servers before named tiers send no tiers.
+    const tier =
+      !options.premium && release.tiers?.[release.methodTiers?.[method]];
+    throw Object.assign(
+      new Error(
+        tier && release.methodTiers[method] > (release.tier ?? 0)
+          ? `${method === "agent" ? "The plugin" : "The GitHub Action"} needs the ${tier} tier.`
+          : "This setup requires access to the published release.",
+      ),
+      { code: "FORBIDDEN" },
+    );
+  }
+  if (command === "init-ci") {
+    const task = release.source?.github?.tasks.find(
+      (item) =>
+        item.name === (options.task ?? release.source.github.defaultTask),
+    );
+    if (!task)
+      throw new Error(
+        "Define github.defaultTask and github.tasks in root knowing.json at the release commit.",
+      );
+    return { task };
+  }
+  if (command === "add-skill") {
+    const skill = options.skill;
+    if (skill && !release.skills.some((item) => item.name === skill))
+      throw Object.assign(
+        new Error("The selected skill requires access or is unavailable."),
+        { code: "FORBIDDEN" },
+      );
+    return {
+      skill,
+      format: skill ? "skills" : "space-skill",
+      agent: options.agent,
+    };
+  }
+  if (options.skill)
+    throw new Error(
+      "Use add-skill --skill for an individual skill; add-plugin follows knowing.json and native plugin manifests.",
+    );
+  let agent = options.agent ?? release.source?.agent?.target;
+  if (agent && !["codex", "claude"].includes(agent))
+    throw new Error("Use --agent codex or --agent claude.");
+  if (!agent) {
+    const plugins = release.formats.filter((format) =>
+      ["codex-plugin", "claude-plugin"].includes(format),
+    );
+    if (plugins.length === 1)
+      agent = plugins[0] === "codex-plugin" ? "codex" : "claude";
+    else
+      throw Object.assign(
+        new Error(
+          "Choose --agent codex or --agent claude, or define agent.target in knowing.json.",
+        ),
+        { code: "AGENT_REQUIRED" },
+      );
+  }
+  const plugin = agent === "codex" ? "codex-plugin" : "claude-plugin";
+  if (release.formats.includes(plugin)) return { format: plugin, agent };
+  const skill = release.source?.agent?.skill;
+  if (!skill)
+    throw new Error(
+      `Define agent.skill in knowing.json or provide a .${agent === "codex" ? "codex" : "claude"}-plugin/plugin.json manifest.`,
+    );
+  return { format: "skills", skill, agent };
+}
+export function taskWorkflow(release, task, installation) {
+  if (
+    task.runner !== "github-action" ||
+    !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*@[a-f0-9]{40}$/.test(
+      task.uses,
+    )
+  )
+    throw new Error(
+      "GitHub tasks must use a commit-pinned github-action runner.",
+    );
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(task.name))
+    throw new Error("Invalid task name.");
+  const inputs = Object.entries(task.inputs ?? {});
+  const secrets = Object.entries(task.secrets ?? {});
+  if (
+    inputs.some(
+      ([key, value]) =>
+        !/^[A-Za-z][A-Za-z0-9_-]*$/.test(key) ||
+        typeof value !== "string" ||
+        value.includes("${{"),
+    ) ||
+    secrets.some(
+      ([key, value]) =>
+        !/^[A-Za-z][A-Za-z0-9_-]*$/.test(key) ||
+        !/^[A-Z][A-Z0-9_]*$/.test(value),
+    )
+  )
+    throw new Error("Unsafe task inputs or secret names.");
+  const permissions = task.permissions;
+  if (
+    !["read", "write"].includes(permissions.contents) ||
+    !["read", "write"].includes(permissions.pullRequests)
+  )
+    throw new Error("Invalid task permissions.");
+  if (Object.keys(task.inputs ?? {}).some((key) => key in (task.secrets ?? {})))
+    throw new Error("Duplicate literal and secret input names.");
+  if (
+    (task.paths ?? []).some(
+      (value) =>
+        typeof value !== "string" ||
+        !/^[A-Za-z0-9_./*!?-]+$/.test(value) ||
+        value.startsWith("/") ||
+        value.split("/").some((part) => [".", "..", ""].includes(part)),
+    )
+  )
+    throw new Error("Unsafe task path filters.");
+  let installSteps = "";
+  if (installation) {
+    const site = siteOrigin(installation.origin);
+    if (
+      !/^[a-f0-9]{64}$/.test(installation.digest) ||
+      !/^[a-z0-9][a-z0-9-]{0,62}\/[a-z0-9][a-z0-9-]{0,62}$/.test(
+        release.identifier,
+      ) ||
+      !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?(?:\+[a-zA-Z0-9.-]+)?$/.test(
+        release.version,
+      ) ||
+      !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(task.skill)
+    )
+      throw new Error("Invalid pinned skill installation.");
+    const script = `.github/knowing-${task.name}.mjs`;
+    installSteps = `      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020\n        with:\n          node-version: '24'\n      - name: Install published review skill\n${installation.requiresToken ? "        env:\n          KNOWING_INSTALL_TOKEN: ${{ secrets.KNOWING_INSTALL_TOKEN }}\n" : ""}        run: |\n          echo '${installation.digest}  ${script}' | sha256sum --check\n          node ${script} add ${release.identifier} --version ${release.version} --skill ${task.skill} --format skills --channel github --site ${site}\n`;
+  }
+  const paths = task.paths?.length
+    ? `    paths: ${JSON.stringify(task.paths)}\n`
+    : "";
+  return `name: ${JSON.stringify(`Knowing ${release.name} — ${task.name}`).replaceAll("${{", "$ { {")}\n# Published release ${release.version}; task skill ${task.skill}\non:\n  pull_request:\n${paths}  workflow_dispatch:\npermissions:\n  contents: ${permissions.contents}\n  pull-requests: ${permissions.pullRequests}\nconcurrency:\n  group: knowing-${task.name}-${"${{ github.event.pull_request.number || github.ref }}"}\n  cancel-in-progress: true\njobs:\n  ${task.name}:\n${secrets.length || installation?.requiresToken ? "    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository\n" : ""}    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683\n        with:\n          persist-credentials: false\n${installSteps}      - uses: ${task.uses}\n${inputs.length || secrets.length ? `        with:\n${inputs.map(([key, value]) => `          ${key}: ${JSON.stringify(value)}\n`).join("")}${secrets.map(([key, value]) => `          ${key}: \${{ secrets.${value} }}\n`).join("")}` : ""}`;
+}
+export async function writeSetupFile(file, content, cwd = process.cwd()) {
+  const root = await realpath(cwd);
+  const destination = path.resolve(root, file);
+  const relative = path.relative(root, destination);
+  if (
+    !relative ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  )
+    throw new Error("Setup files must stay inside the project.");
+  await safeDirectory(path.dirname(destination));
+  try {
+    await writeFile(destination, content, { flag: "wx", mode: 0o644 });
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new Error(
+        `Existing ${file} was preserved. Review it before replacing it.`,
+      );
+    throw error;
+  }
+  return destination;
+}
+async function setupRelease(command, target, flag, switches) {
+  const configDir = await configurationDirectory(flag("config-dir"));
+  let defaultOrigin;
+  try {
+    defaultOrigin = JSON.parse(
+      await readFile(
+        path.join(
+          configDir
+            ? path.resolve(configDir)
+            : path.join(homedir(), ".config", "knowing-skills"),
+          "default-site.json",
+        ),
+        "utf8",
+      ),
+    ).origin;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const { origin, input } = releaseTarget(
+    target,
+    flag("site") ?? process.env.KNOWING_SITE ?? defaultOrigin,
+  );
+  if (flag("version")) input.version = flag("version");
+  input.channel =
+    command === "add-agent"
+      ? "agent"
+      : command === "init-ci"
+        ? "github"
+        : "skills";
+  let options = {
+    skill: flag("skill"),
+    agent: flag("agent"),
+    task: flag("task"),
+    free: switches.free,
+    premium: switches.premium,
+  };
+  let resolvedRelease;
+  let requestedArtifact;
+  // After a login for this release, the browser continues to its access page.
+  let browserOnAccessPage = false;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const auth = await credentials(origin, configDir);
+    try {
+      const release = await rpc(
+        origin,
+        "resolve",
+        input,
+        false,
+        process.env.KNOWING_INSTALL_TOKEN ?? auth.token,
+      );
+      resolvedRelease = release;
+      // Every later attempt installs this exact release.
+      input.version = release.version;
+      let setup;
+      try {
+        setup = releaseSetup(command, release, options);
+      } catch (error) {
+        if (error.code !== "AGENT_REQUIRED" || !process.stdin.isTTY)
+          throw error;
+        const prompt = createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        });
+        try {
+          options.agent = (
+            await prompt.question("Install for codex or claude? ")
+          ).trim();
+        } finally {
+          prompt.close();
+        }
+        setup = releaseSetup(command, release, options);
+      }
+      if (command === "init-ci") {
+        const selectedSkill = release.skills.find(
+          (item) => item.name === setup.task.skill,
+        );
+        const requiresToken =
+          selectedSkill.access === "restricted" ||
+          selectedSkill.tier === "paid" ||
+          (release.methodTiers?.github ?? 0) > 0;
+        const script = await readFile(new URL(import.meta.url), "utf8");
+        const digest = createHash("sha256").update(script).digest("hex");
+        const helper = await writeSetupFile(
+          `.github/knowing-${setup.task.name}.mjs`,
+          script,
+        );
+        let file;
+        try {
+          file = await writeSetupFile(
+            `.github/workflows/knowing-${setup.task.name}.yml`,
+            taskWorkflow(release, setup.task, {
+              origin,
+              digest,
+              requiresToken,
+            }),
+          );
+        } catch (error) {
+          await rm(helper);
+          throw error;
+        }
+        if (requiresToken)
+          print(
+            `Set the KNOWING_INSTALL_TOKEN repository secret to an install-only token with access to this release:\nknowing login --site ${origin} --install-only | gh secret set KNOWING_INSTALL_TOKEN\nIt only installs releases, never reads your spaces or uses hosted answers, expires after 30 days and can be revoked from Authorized devices.`,
+          );
+        print(
+          `Created ${file}\nRelease ${release.version}, task ${setup.task.name}. Commit and push after reviewing the workflow.`,
+        );
+        if (Object.keys(setup.task.secrets).length)
+          print(
+            `Set these GitHub Actions secrets before running: ${[...new Set(Object.values(setup.task.secrets))].join(", ")}`,
+          );
+        return;
+      }
+      const expected = {
+        identifier: release.identifier,
+        version: release.version,
+        channel: input.channel,
+        skill: setup.skill,
+        format: setup.format,
+        ...(options.free
+          ? { tier: "free" }
+          : options.premium
+            ? { tier: "paid" }
+            : {}),
+      };
+      requestedArtifact = expected;
+      const artifact = validateArtifact(
+        await rpc(
+          origin,
+          "artifact",
+          expected,
+          false,
+          process.env.KNOWING_INSTALL_TOKEN ?? auth.token,
+        ),
+        expected,
+      );
+      // Create the MCP file first so an existing configuration cannot leave a partial skill installation.
+      let mcpFile;
+      if (command === "add-agent" && setup.format === "skills" && release.mcp) {
+        if (setup.agent !== "claude")
+          throw new Error(
+            "Repo MCP configuration for Codex requires a Codex plugin manifest. Existing Codex configuration is never overwritten.",
+          );
+        const mcp = JSON.parse(release.mcp);
+        if (
+          !mcp ||
+          typeof mcp.mcpServers !== "object" ||
+          Array.isArray(mcp.mcpServers)
+        )
+          throw new Error(".mcp.json must contain mcpServers.");
+        mcpFile = await writeSetupFile(".mcp.json", release.mcp);
+      }
+      let directories;
+      try {
+        directories = await installArtifact(artifact, { agent: setup.agent });
+      } catch (error) {
+        if (mcpFile) await rm(mcpFile);
+        throw error;
+      }
+      print(
+        `Installed ${release.name}@${release.version}:\n${directories.join("\n")}`,
+      );
+      if (
+        command === "add-skill" &&
+        !setup.skill &&
+        !options.free &&
+        !release.fullAccess
+      )
+        print(
+          `More of this release is in paid tiers: ${releaseAccessUrl(origin, release.releaseId)}`,
+        );
+      const registrationDirectory = await preparePluginRegistration(
+        artifact,
+        directories[0],
+      );
+      printPluginRegistration(artifact, [registrationDirectory]);
+      if (
+        command === "add-agent" &&
+        artifact.format.endsWith("-plugin") &&
+        !switches.noRegister
+      ) {
+        try {
+          await registerPlugin(artifact, registrationDirectory);
+        } catch (error) {
+          throw new Error(
+            `Plugin files are ready at ${directories[0]}, but native registration failed: ${error.message}. Use the printed commands to finish setup.`,
+          );
+        }
+        print("Plugin registered. Restart your coding agent to load it.");
+      }
+      return;
+    } catch (error) {
+      if (!["FORBIDDEN", "UNAUTHORIZED"].includes(error.code)) {
+        // A private space looks missing to visitors who aren't signed in.
+        if (
+          error.code === "NOT_FOUND" &&
+          !resolvedRelease &&
+          !auth.token &&
+          !process.env.KNOWING_INSTALL_TOKEN
+        )
+          error.message += ` If this space is private, run knowing login --site ${origin} and try again.`;
+        throw error;
+      }
+      if (!resolvedRelease) throw error;
+      const token = process.env.KNOWING_INSTALL_TOKEN ?? auth.token;
+      // The setup check runs before an artifact request exists.
+      const request = requestedArtifact ?? {
+        identifier: resolvedRelease.identifier,
+        version: resolvedRelease.version,
+        channel: input.channel,
+        ...(command === "add-skill" && options.skill
+          ? { skill: options.skill }
+          : {}),
+        ...(options.premium ? { tier: "paid" } : {}),
+      };
+      const check = () => rpc(origin, "installAccess", request, false, token);
+      let access = await check();
+      const accessUrl = releaseAccessUrl(origin, access.releaseId);
+      const needs = access.tier
+        ? `This needs the ${access.tier} tier.`
+        : "This needs access to the release.";
+      // Revoked access and access that isn't sold can't be fixed in a browser.
+      const stopUnlessBuyable = () => {
+        if (access.status === "revoked")
+          throw new Error(
+            `Your access to this release was revoked. Contact the creator, or see ${accessUrl}`,
+          );
+        if (access.status === "unavailable")
+          throw new Error(`${needs} It isn't for sale right now: ${accessUrl}`);
+      };
+      if (access.status === "granted") {
+        if (attempt < 2) continue;
+        throw new Error(`${error.message} Run the command again.`);
+      }
+      stopUnlessBuyable();
+      // Unattended runs can't sign in or pay, so they stop with the next step.
+      const unattended = process.env.CI || process.env.KNOWING_INSTALL_TOKEN;
+      if (unattended || attempt === 2)
+        throw new Error(
+          `${needs} Get access with your Knowing account at ${accessUrl}, then run the command again.${unattended ? ` CI installs with a KNOWING_INSTALL_TOKEN from that account: knowing login --site ${origin} --install-only` : ""}`,
+        );
+      if (access.status === "signin") {
+        print(
+          "This installation needs your Knowing account. Sign in in your browser; installation continues automatically.",
+        );
+        await main([
+          "login",
+          "--site",
+          origin,
+          "--release",
+          access.releaseId,
+          ...(configDir ? ["--config-dir", configDir] : []),
+          ...(switches.noBrowser ? ["--no-browser"] : []),
+        ]);
+        browserOnAccessPage = true;
+        continue;
+      }
+      print(
+        `${needs} Get access in your browser: ${accessUrl}\nInstallation continues automatically after access is confirmed. If this command stops, run it again after paying.`,
+      );
+      if (!switches.noBrowser && !browserOnAccessPage) openBrowser(accessUrl);
+      browserOnAccessPage = true;
+      access = await waitForReleaseAccess(check);
+      stopUnlessBuyable();
+    }
+  }
+}
+/** The release's access options, through sign-in when the browser needs it. */
+export function releaseAccessUrl(origin, releaseId) {
+  return `${origin}/join?callbackURL=${encodeURIComponent(`/skills?release=${encodeURIComponent(releaseId)}`)}`;
+}
+/**
+ * Polls an install's access while the buyer can still act in the browser,
+ * and returns it once they can't: granted, revoked or not for sale. Network
+ * failures are retried a few times; server answers are not.
+ */
+export async function waitForReleaseAccess(
+  load,
+  {
+    timeoutMs = 600000,
+    pollMs = 3000,
+    retries = 3,
+    sleep = wait,
+    now = () => performance.now(),
+  } = {},
+) {
+  const deadline = now() + timeoutMs;
+  let failures = 0;
+  while (now() < deadline) {
+    let access;
+    try {
+      access = await load();
+      failures = 0;
+    } catch (error) {
+      if (error.code || ++failures > retries) throw error;
+    }
+    if (access && !["signin", "purchase"].includes(access.status))
+      return access;
+    await sleep(pollMs);
+  }
+  throw new Error(
+    "Access was not confirmed in time. Finish in your browser, then run the install command again.",
+  );
+}
+export async function preparePluginRegistration(artifact, directory) {
+  if (artifact.format !== "codex-plugin") return directory;
+  const root = path.dirname(await realpath(directory));
+  const catalog = JSON.parse(
+    artifact.files.find(
+      (file) => file.path === ".agents/plugins/marketplace.json",
+    ).content,
+  );
+  catalog.plugins[0].source.path = `./${path.basename(directory)}`;
+  await writeSetupFile(
+    ".agents/plugins/marketplace.json",
+    JSON.stringify(catalog, null, 2),
+    root,
+  );
+  return root;
+}
+export async function registerPlugin(artifact, directory, run = runFile) {
+  const codex = artifact.format === "codex-plugin";
+  const file = codex
+    ? ".agents/plugins/marketplace.json"
+    : ".claude-plugin/marketplace.json";
+  const catalog = JSON.parse(
+    artifact.files.find((item) => item.path === file).content,
+  );
+  const command = codex ? "codex" : "claude";
+  await run(command, ["plugin", "marketplace", "add", directory], {
+    timeout: 120000,
+  });
+  await run(
+    command,
+    [
+      "plugin",
+      codex ? "add" : "install",
+      `${catalog.plugins[0].name}@${catalog.name}`,
+    ],
+    { timeout: 120000 },
+  );
+}
+function printPluginRegistration(artifact, directories) {
+  const directory = `'${directories[0].replaceAll("'", "'\\''")}'`;
+  if (artifact.format === "claude-plugin") {
+    const catalog = artifact.files.find(
+      (file) => file.path === ".claude-plugin/marketplace.json",
+    );
+    if (catalog) {
+      const data = JSON.parse(catalog.content);
+      print(
+        `Register and install with:\nclaude plugin marketplace add ${directory}\nclaude plugin install ${data.plugins[0].name}@${data.name}`,
+      );
+    } else print(`Load with: claude --plugin-dir ${directory}`);
+  }
+  if (artifact.format === "codex-plugin") {
+    const catalog = JSON.parse(
+      artifact.files.find(
+        (file) => file.path === ".agents/plugins/marketplace.json",
+      ).content,
+    );
+    print(
+      `Register and install with:\ncodex plugin marketplace add ${directory}\ncodex plugin add ${catalog.plugins[0].name}@${catalog.name}`,
+    );
+  }
+}
+
+export async function main(args) {
+  const [name, ...rest] = args;
+  // add-agent is the earlier name for add-plugin.
+  const command = name === "add-plugin" ? "add-agent" : name;
+  const flag = (name) => {
+    const index = rest.indexOf(`--${name}`);
+    return index < 0 ? undefined : rest[index + 1];
+  };
+  if (["add-skill", "add-agent", "init-ci"].includes(command)) {
+    await setupRelease(command, rest[0], flag, {
+      free: rest.includes("--free"),
+      premium: rest.includes("--premium"),
+      noBrowser: rest.includes("--no-browser"),
+      noRegister: rest.includes("--no-register"),
+    });
+    return;
+  }
+  if (!["login", "logout", "token", "add"].includes(command) || !flag("site")) {
+    print(
+      "Usage: node knowing-skills.mjs add-skill|add-plugin|init-ci SPACE_URL [--agent codex|claude]\n       node knowing-skills.mjs login|logout|token --site https://your-site\n       node knowing-skills.mjs login --site https://your-site --install-only (prints a CI install token)\n       node knowing-skills.mjs add author/package --version 1.0.0 [--skill name] [--format skills|space-skill|codex-plugin|claude-plugin] [--agent codex|claude] --site https://your-site",
+    );
+    return;
+  }
+  const origin = siteOrigin(flag("site"));
+  const configDir = await configurationDirectory(flag("config-dir"));
+  if (command === "logout") {
+    await rm(credentialsFile(origin, configDir), { force: true });
+    print(
+      "Local token removed. Revoke the terminal in Account settings → Authorized devices to disable it on the server.",
+    );
+    return;
+  }
+  if (command === "token") {
+    const { token } = await credentials(origin, configDir);
+    if (!token?.startsWith("knc_"))
+      throw new Error(
+        `Run knowing login --site ${origin} to get a customer token.`,
+      );
+    print(token);
+    return;
+  }
+  if (command === "login") {
+    // An install-only token is for the KNOWING_INSTALL_TOKEN CI secret: it
+    // can't read spaces over MCP, so it's printed alone on stdout and never
+    // replaces the saved customer login.
+    const installOnly = rest.includes("--install-only");
+    const note = installOnly
+      ? (value) => process.stderr.write(`${value}\n`)
+      : print;
+    const request = await rpc(
+      origin,
+      "startDevice",
+      {
+        label:
+          flag("label") ??
+          `${installOnly ? "CI install" : "Terminal"} ${randomBytes(3).toString("hex")}`,
+        ...(installOnly ? { installOnly } : {}),
+      },
+      true,
+    );
+    // An install waiting on a release continues to its access page.
+    const authorizeUrl = `${origin}/skills/authorize?code=${request.code}${flag("release") ? `&release=${encodeURIComponent(flag("release"))}` : ""}`;
+    note(
+      `Open ${authorizeUrl}\nConfirm code ${request.code} in your browser. Waiting for approval…`,
+    );
+    if (!rest.includes("--no-browser")) openBrowser(authorizeUrl);
+    const deadline = Date.now() + request.expiresIn * 1000;
+    while (Date.now() < deadline) {
+      await wait(request.interval * 1000);
+      const result = await rpc(
+        origin,
+        "pollDevice",
+        { deviceCode: request.deviceCode },
+        true,
+      );
+      if (result.status !== "approved") continue;
+      if (installOnly) {
+        if (result.token.startsWith("knc_"))
+          throw new Error(
+            "This Knowing site can't issue install-only tokens yet. Revoke the new terminal under Authorized devices.",
+          );
+        print(result.token);
+        note(
+          "Store this install-only token as the KNOWING_INSTALL_TOKEN repository secret. It isn't saved on this machine and expires in 30 days.",
+        );
+        return;
+      }
+      const file = credentialsFile(origin, configDir);
+      await saveConfiguration(file, { token: result.token });
+      const defaults = path.join(path.dirname(file), "default-site.json");
+      await saveConfiguration(defaults, { origin });
+      print("Connected. Your token is stored locally and expires in 30 days.");
+      return;
+    }
+    throw new Error("Login expired. Start login again.");
+  }
+  const identifier = rest[0];
+  const version = flag("version");
+  const skill = flag("skill");
+  const format = flag("format") ?? "skills";
+  if (
+    !/^[a-z0-9][a-z0-9-]{0,62}\/[a-z0-9][a-z0-9-]{0,62}$/.test(
+      identifier ?? "",
+    ) ||
+    !["skills", "space-skill", "codex-plugin", "claude-plugin"].includes(
+      format,
+    ) ||
+    (skill && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill))
+  )
+    throw new Error("Invalid package, format or skill.");
+  const auth = await credentials(origin, configDir);
+  const expected = {
+    identifier,
+    version,
+    skill,
+    format,
+    ...(flag("channel") ? { channel: flag("channel") } : {}),
+  };
+  const token = process.env.KNOWING_INSTALL_TOKEN ?? auth.token;
+  let artifact;
+  try {
+    artifact = validateArtifact(
+      await rpc(origin, "artifact", expected, false, token),
+      expected,
+    );
+  } catch (error) {
+    if (!["FORBIDDEN", "UNAUTHORIZED"].includes(error.code)) throw error;
+    // Older servers have no access check; the original error still stands.
+    const access = await rpc(
+      origin,
+      "installAccess",
+      expected,
+      false,
+      token,
+    ).catch(() => undefined);
+    throw new Error(
+      `${error.message}${access ? ` Get access with your Knowing account at ${releaseAccessUrl(origin, access.releaseId)}, then run the command again.` : ""}${process.env.CI || process.env.KNOWING_INSTALL_TOKEN ? ` CI installs with a KNOWING_INSTALL_TOKEN from that account: knowing login --site ${origin} --install-only` : ""}`,
+    );
+  }
+  const directories = await installArtifact(artifact, { agent: flag("agent") });
+  print(
+    `Installed ${identifier}@${artifact.version}:\n${directories.join("\n")}`,
+  );
+  const registrationDirectory = await preparePluginRegistration(
+    artifact,
+    directories[0],
+  );
+  printPluginRegistration(artifact, [registrationDirectory]);
+}
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(await realpath(process.argv[1])).href
+)
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });