knowingfyi 0.3.0 → 0.3.1

package/README.md

@@ -55,7 +55,7 @@ Publishing and source-grounded docs are also available through `publish`, `sync`
 npx knowingfyi login --site https://your-knowing-host
 ```
 
-The browser approval stores a customer token locally for 30 days, and the commands send it to that host. On another machine or in CI, set `KNOWING_CUSTOMER_TOKEN` with `KNOWING_SITE` naming the same host. `logout` removes the local token; revoke the terminal under Authorized devices to disable it. Customer-token reading, `knowing token`, `--install-only` and the `KNOWING_SITE` check arrive with the release after 0.1.1.
+The browser approval stores a customer token locally until revoked, and the commands send it to that host. On another machine or in CI, set `KNOWING_CUSTOMER_TOKEN` with `KNOWING_SITE` naming the same host. `logout` removes the local token; revoke the terminal under Authorized devices to disable it. Customer-token reading, `knowing token`, `--install-only` and the `KNOWING_SITE` check arrive with the release after 0.1.1.
 
 ## When your Knowing host changes
 
@@ -66,3 +66,5 @@ Update `KNOWING_SITE`, MCP server URLs and any vendored workflow project URLs de
 The CLI rejects API redirects, and publishing/install secrets have different capabilities from customer logins. Existing self-hosted and local origins remain supported. Operators can use the [platform domain cutover runbook](https://github.com/BrickspaceLab/knowing/blob/main/docs/knowing/platform-domain-cutover.md) to plan compatibility and rollback.
 
 Node.js 24 or newer is required. See [authoring skills and source configuration](https://github.com/BrickspaceLab/knowing/blob/main/docs/knowing/release-source.md).
+
+Interactive native plugin installation installs and registers available free skills first, then opens account authorization and waits for paid access before upgrading the same pinned plugin and registering it again. `--free` skips the upgrade; CI and install-token runs never wait for browser checkout. Locally modified plugin files are preserved. This flow requires the next npm CLI release.

package/knowing-skills.mjs

@@ -6,6 +6,7 @@ import { pathToFileURL } from "node:url";
 import {
   mkdir,
   readFile,
+  readdir,
   writeFile,
   lstat,
   realpath,
@@ -184,9 +185,43 @@ async function safeDirectory(directory) {
       throw new Error(`Unsafe directory: ${current}`);
   }
 }
+async function identicalSkill(directory, files, prefix) {
+  const pending = [directory];
+  const expected = new Map(
+    files
+      .filter((file) => file.path.startsWith(prefix))
+      .map((file) => [file.path.slice(prefix.length), file]),
+  );
+  if ((await lstat(directory)).isSymbolicLink()) return false;
+  let count = 0;
+  while (pending.length) {
+    const current = pending.pop();
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) return false;
+      if (entry.isDirectory()) {
+        pending.push(target);
+        continue;
+      }
+      const file = expected.get(
+        path.relative(directory, target).split(path.sep).join("/"),
+      );
+      if (!entry.isFile() || !file) return false;
+      const content = Buffer.from(
+        file.content,
+        file.encoding === "base64" ? "base64" : "utf8",
+      );
+      if (!(await readFile(target)).equals(content)) return false;
+      count++;
+    }
+  }
+  return count === expected.size;
+}
 export async function installArtifact(artifact, options = {}) {
   const cwd = await realpath(path.resolve(options.cwd ?? process.cwd()));
   const created = [];
+  const reused = new Set();
+  const backups = new Map();
   try {
     if (["skills", "project-skill", "space-skill"].includes(artifact.format)) {
       const base = path.join(
@@ -205,12 +240,34 @@ export async function installArtifact(artifact, options = {}) {
       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);
+        try {
+          await mkdir(dest);
+          created.push(dest);
+        } catch (error) {
+          if (error.code !== "EEXIST" || !options.reuseIdentical) throw error;
+          const prefix = `skills/${name}/`;
+          if (await identicalSkill(dest, artifact.files, prefix)) {
+            reused.add(dest);
+          } else if (
+            options.previousArtifact?.files.some((file) =>
+              file.path.startsWith(prefix),
+            ) &&
+            (await identicalSkill(dest, options.previousArtifact.files, prefix))
+          ) {
+            const backup = `${dest}.upgrade-${randomBytes(12).toString("hex")}`;
+            await rename(dest, backup);
+            backups.set(dest, backup);
+            await mkdir(dest);
+            created.push(dest);
+          } else {
+            throw error;
+          }
+        }
       }
       for (const file of artifact.files.filter((f) =>
         f.path.startsWith("skills/"),
       )) {
+        if (reused.has(path.join(base, file.path.split("/")[1]))) continue;
         const dest = path.join(base, file.path.slice(7));
         await safeDirectory(path.dirname(dest));
         await writeFile(
@@ -229,9 +286,27 @@ export async function installArtifact(artifact, options = {}) {
       );
       await safeDirectory(base);
       const dest = path.join(base, artifact.format);
-      await mkdir(dest);
-      created.push(dest);
-      for (const file of artifact.files) {
+      try {
+        await mkdir(dest);
+        created.push(dest);
+      } catch (error) {
+        if (error.code !== "EEXIST" || !options.reuseIdentical) throw error;
+        if (await identicalSkill(dest, artifact.files, "")) {
+          reused.add(dest);
+        } else if (
+          options.previousArtifact &&
+          (await identicalSkill(dest, options.previousArtifact.files, ""))
+        ) {
+          const backup = `${dest}.upgrade-${randomBytes(12).toString("hex")}`;
+          await rename(dest, backup);
+          backups.set(dest, backup);
+          await mkdir(dest);
+          created.push(dest);
+        } else {
+          throw error;
+        }
+      }
+      for (const file of reused.has(dest) ? [] : artifact.files) {
         const output = path.join(dest, file.path);
         await safeDirectory(path.dirname(output));
         await writeFile(
@@ -241,10 +316,14 @@ export async function installArtifact(artifact, options = {}) {
         );
       }
     }
-    return created;
+    for (const backup of backups.values())
+      await rm(backup, { recursive: true }).catch(() => {});
+    return [...created, ...reused];
   } catch (error) {
     for (const directory of created.reverse())
       await rm(directory, { recursive: true, force: true });
+    for (const [destination, backup] of backups)
+      await rename(backup, destination);
     if (error.code === "EEXIST")
       throw new Error(
         "A destination already exists. Existing files were preserved; choose another project or remove the old installation yourself.",
@@ -646,7 +725,7 @@ async function setupRelease(command, target, flag, switches) {
         }
         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 projects or uses hosted answers, expires after 30 days and can be revoked from Authorized devices.`,
+            `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 projects or uses hosted answers, stays active until revoked from Authorized devices.`,
           );
         print(
           `Created ${file}\nRelease ${release.version}, task ${setup.task.name}. Commit and push after reviewing the workflow.`,
@@ -680,6 +759,23 @@ async function setupRelease(command, target, flag, switches) {
         ),
         expected,
       );
+      const freeExpected = { ...expected, tier: "free" };
+      let previousArtifact;
+      if (
+        !options.free &&
+        (options.premium || (release.tier ?? 0) > 0) &&
+        !setup.skill
+      ) {
+        try {
+          previousArtifact = validateArtifact(
+            await rpc(origin, "artifact", freeExpected, false),
+            freeExpected,
+          );
+        } catch (error) {
+          // A paid-only or private release has no anonymous free installation to upgrade.
+          if (!["FORBIDDEN", "NOT_FOUND"].includes(error.code)) throw error;
+        }
+      }
       // 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) {
@@ -698,7 +794,11 @@ async function setupRelease(command, target, flag, switches) {
       }
       let directories;
       try {
-        directories = await installArtifact(artifact, { agent: setup.agent });
+        directories = await installArtifact(artifact, {
+          agent: setup.agent,
+          reuseIdentical: true,
+          previousArtifact,
+        });
       } catch (error) {
         if (mcpFile) await rm(mcpFile);
         throw error;
@@ -710,11 +810,20 @@ async function setupRelease(command, target, flag, switches) {
         command === "add-skill" &&
         !setup.skill &&
         !options.free &&
+        !options.premium &&
         !release.fullAccess
-      )
+      ) {
+        const upgradeUrl = releaseAccessUrl(origin, release.releaseId);
         print(
-          `More of this release is in paid tiers: ${releaseAccessUrl(origin, release.releaseId)}`,
+          `Free skills installed. Compare paid tiers and their benefits: ${upgradeUrl}`,
         );
+        if (
+          !switches.noBrowser &&
+          !process.env.CI &&
+          !process.env.KNOWING_INSTALL_TOKEN
+        )
+          openBrowser(upgradeUrl);
+      }
       const registrationDirectory = await preparePluginRegistration(
         artifact,
         directories[0],
@@ -734,6 +843,40 @@ async function setupRelease(command, target, flag, switches) {
         }
         print("Plugin registered. Restart your coding agent to load it.");
       }
+      if (
+        command === "add-agent" &&
+        artifact.format.endsWith("-plugin") &&
+        !options.free &&
+        !options.premium &&
+        !release.fullAccess &&
+        // Only a free installation can be replaced; a paid tier's files differ from it.
+        !((release.tier ?? 0) > 0) &&
+        process.stdin.isTTY &&
+        !process.env.CI &&
+        !process.env.KNOWING_INSTALL_TOKEN
+      ) {
+        print(
+          "Free plugin installed. Continue in your browser to sign in and compare paid tiers. The plugin upgrades automatically after purchase.",
+        );
+        try {
+          await setupRelease(
+            command,
+            target,
+            (name) =>
+              name === "agent"
+                ? setup.agent
+                : name === "version"
+                  ? release.version
+                  : flag(name),
+            { ...switches, premium: true },
+          );
+        } catch (error) {
+          // A failed upgrade rolls back its files; the free installation above already succeeded.
+          print(
+            `Paid upgrade did not finish: ${error.message} Compare paid tiers: ${releaseAccessUrl(origin, release.releaseId)}`,
+          );
+        }
+      }
       return;
     } catch (error) {
       if (!["FORBIDDEN", "UNAUTHORIZED"].includes(error.code)) {
@@ -811,9 +954,9 @@ async function setupRelease(command, target, flag, switches) {
     }
   }
 }
-/** The release's access options, through sign-in when the browser needs it. */
+/** Public plan comparison; authentication happens when acquiring access. */
 export function releaseAccessUrl(origin, releaseId) {
-  return `${origin}/join?callbackURL=${encodeURIComponent(`/skills?release=${encodeURIComponent(releaseId)}`)}`;
+  return `${origin}/skills/releases/${encodeURIComponent(releaseId)}`;
 }
 /**
  * Polls an install's access while the buyer can still act in the browser,
@@ -857,11 +1000,21 @@ export async function preparePluginRegistration(artifact, directory) {
     ).content,
   );
   catalog.plugins[0].source.path = `./${path.basename(directory)}`;
-  await writeSetupFile(
-    ".agents/plugins/marketplace.json",
-    JSON.stringify(catalog, null, 2),
-    root,
-  );
+  const file = ".agents/plugins/marketplace.json";
+  const content = JSON.stringify(catalog, null, 2);
+  const destination = path.join(root, file);
+  try {
+    const stat = await lstat(destination);
+    if (
+      !stat.isSymbolicLink() &&
+      stat.isFile() &&
+      (await readFile(destination, "utf8")) === content
+    )
+      return root;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  await writeSetupFile(file, content, root);
   return root;
 }
 export async function registerPlugin(artifact, directory, run = runFile) {
@@ -994,7 +1147,7 @@ export async function main(args) {
           );
         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.",
+          "Store this install-only token as the KNOWING_INSTALL_TOKEN repository secret. It isn't saved on this machine and stays active until revoked.",
         );
         return;
       }
@@ -1002,7 +1155,9 @@ export async function main(args) {
       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.");
+      print(
+        "Connected. Your token is stored locally and stays active until revoked.",
+      );
       return;
     }
     throw new Error("Login expired. Start login again.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowingfyi",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Install source-defined Knowing skills and agents and configure GitHub Actions.",
   "type": "module",
   "bin": {