threadnote 0.1.0 → 0.2.0

package/README.md

@@ -89,6 +89,8 @@ The bundled `config/seed-manifest.example.yaml` is only an example. Each develop
   current checkout.
 - `start`: starts `openviking-server` on `127.0.0.1:1933`.
 - `stop`: stops the detached server pid or macOS LaunchAgent.
+- `uninstall`: removes Threadnote shims, MCP config, launchd config, and managed user instructions. Memories are
+  preserved by default; pass `--erase-memories` to delete `THREADNOTE_HOME`.
 - `init-manifest`: creates or updates `~/.openviking/seed-manifest.yaml` from one or more developer repo roots.
 - `seed`: imports curated repo guidance and docs from the manifest.
 - `seed-skills`: imports global and repo-local `SKILL.md` files as a searchable resource catalog. Use
@@ -164,6 +166,29 @@ If a future OpenViking build exposes a healthy native endpoint, install it expli
 threadnote mcp-install claude --native-http --apply
 ```
 
+## Uninstall
+
+Preview removal:
+
+```bash
+threadnote uninstall --dry-run
+```
+
+Remove Threadnote setup while keeping local OpenViking memories:
+
+```bash
+threadnote uninstall
+```
+
+Erase local memories too:
+
+```bash
+threadnote uninstall --erase-memories
+```
+
+`uninstall` removes only Threadnote-managed files and agent config. The npm, Bun, or Deno package remains installed;
+remove that with the package manager you used to install it.
+
 ## Notes
 
 OpenViking itself is not vendored here. This prototype installs and controls a local service and should get legal and

package/dist/threadnote.cjs

@@ -3491,11 +3491,12 @@ var import_promises6 = require("node:fs/promises");
 var import_promises7 = require("node:fs/promises");
 var import_node_path5 = require("node:path");
 var import_node_path6 = require("node:path");
+var import_promises8 = require("node:fs/promises");
 var import_node_path7 = require("node:path");
 var import_node_child_process = require("node:child_process");
-var import_promises8 = require("node:fs/promises");
-var import_node_os3 = require("node:os");
 var import_promises9 = require("node:fs/promises");
+var import_node_os3 = require("node:os");
+var import_promises10 = require("node:fs/promises");
 
 // node_modules/.deno/js-yaml@4.1.1/node_modules/js-yaml/dist/js-yaml.mjs
 function isNothing(subject) {
@@ -6178,6 +6179,13 @@ async function main() {
   program2.command("stop").description("Stop the local OpenViking server or LaunchAgent").option("--dry-run", "Print the stop actions without running them").action(async (options) => {
     await runStop(getRuntimeConfig(program2), options);
   });
+  program2.command("uninstall").description("Remove Threadnote setup and optionally erase local memories").option("--dry-run", "Print uninstall actions without making changes").option(
+    "--mcp <clients>",
+    "MCP clients to remove: available, all, none, codex, claude, or comma-separated list",
+    "available"
+  ).option("--preserve-memories", "Preserve THREADNOTE_HOME and OpenViking memories (default)").option("--erase-memories", "Delete THREADNOTE_HOME, including all OpenViking memories").action(async (options) => {
+    await runUninstall(getRuntimeConfig(program2), options);
+  });
   program2.command("seed").description("Seed curated context from the manifest; never indexes whole repos by default").option("--dry-run", "Print files and ov commands without importing").option("--manifest <path>", "Manifest path for this seed run").action(async (options) => {
     await runSeed(getRuntimeConfig(program2, options.manifest), options);
   });
@@ -6318,7 +6326,7 @@ async function runRepair(config, options) {
   } else {
     console.log("Skipping server health repair because --no-start was provided.");
   }
-  const mcpClients = await resolveRepairMcpClients(options.mcp ?? "available");
+  const mcpClients = await resolveMcpClients(options.mcp ?? "available", "repair");
   if (mcpClients.length === 0) {
     console.log("Skipping MCP config repair.");
   } else {
@@ -6330,6 +6338,28 @@ async function runRepair(config, options) {
   console.log("\nPost-repair doctor:");
   await runDoctor(config, { dryRun, strict: false });
 }
+async function runUninstall(config, options) {
+  const dryRun = options.dryRun === true;
+  if (options.eraseMemories === true && options.preserveMemories === true) {
+    throw new Error("Use either --erase-memories or --preserve-memories, not both.");
+  }
+  console.log("Uninstalling local Threadnote setup.");
+  await runStop(config, { dryRun });
+  await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
+  await removeLaunchAgent(dryRun);
+  await removeMcpConfigs(options.mcp ?? "available", dryRun);
+  await removeMcpSnippets(config, dryRun);
+  await removeCommandShim(dryRun);
+  await removeUserAgentInstructions(dryRun);
+  if (options.eraseMemories === true) {
+    await eraseThreadnoteHome(config.agentContextHome, dryRun);
+  } else {
+    console.log(`Preserving local memories and OpenViking home: ${config.agentContextHome}`);
+    console.log("Use --erase-memories to delete this directory during uninstall.");
+  }
+  console.log("Uninstall complete.");
+  console.log("The package remains installed. Remove it with your package manager if desired.");
+}
 async function repairManifest(config, dryRun) {
   try {
     await readSeedManifest(config.manifestPath);
@@ -6373,11 +6403,11 @@ async function repairManifest(config, dryRun) {
   const currentContent = await readFileIfExists(config.manifestPath);
   if (currentContent !== void 0) {
     const backupPath = `${config.manifestPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises9.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
     await (0, import_promises2.chmod)(backupPath, 384);
     console.log(`Backup: ${backupPath}`);
   }
-  await (0, import_promises9.writeFile)(config.manifestPath, output, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(config.manifestPath, output, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(config.manifestPath, 384);
   console.log(`Wrote replacement manifest: ${config.manifestPath}`);
 }
@@ -6425,7 +6455,7 @@ async function runStart(config, options) {
   const logFd = (0, import_node_fs3.openSync)(logPath, "a");
   const child = spawnDetachedServerWithLog(server, args, logFd);
   child.unref();
-  await (0, import_promises9.writeFile)((0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
+  await (0, import_promises10.writeFile)((0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
 `, "utf8");
   console.log(`Started OpenViking with pid ${child.pid}. Logs: ${logPath}`);
 }
@@ -6445,7 +6475,11 @@ function spawnDetachedServer(server, args, logFd) {
 async function runStop(config, options) {
   const launchAgentPath = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
   if ((0, import_node_os2.platform)() === "darwin") {
-    await maybeRun(options.dryRun === true, "launchctl", ["unload", launchAgentPath], { allowFailure: true });
+    if (options.dryRun === true || await exists(launchAgentPath)) {
+      await maybeRun(options.dryRun === true, "launchctl", ["unload", launchAgentPath], { allowFailure: true });
+    } else {
+      console.log(`No LaunchAgent found: ${launchAgentPath}`);
+    }
   }
   const pidPath = (0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid");
   const pidText = await readFileIfExists(pidPath);
@@ -6541,7 +6575,7 @@ async function runInitManifest(config, options) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(manifestPath), false);
-  await (0, import_promises9.writeFile)(manifestPath, output, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(manifestPath, output, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(manifestPath, 384);
   console.log(`Wrote manifest: ${manifestPath}`);
   console.log("Seed with:");
@@ -6920,9 +6954,9 @@ async function writeTemplateIfMissing(options) {
       return;
     }
     const backupPath = `${options.destinationPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises9.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
     await (0, import_promises2.chmod)(backupPath, 384);
-    await (0, import_promises9.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
     await (0, import_promises2.chmod)(options.destinationPath, 384);
     console.log(`Repaired generated config: ${options.destinationPath}`);
     console.log(`Backup: ${backupPath}`);
@@ -6934,7 +6968,7 @@ async function writeTemplateIfMissing(options) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(options.destinationPath), false);
-  await (0, import_promises9.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(options.destinationPath, 384);
   console.log(`Wrote ${options.destinationPath}`);
 }
@@ -6956,10 +6990,23 @@ async function installCommandShim(dryRun) {
     return;
   }
   await ensureDirectory(binDir, false);
-  await (0, import_promises9.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
+  await (0, import_promises10.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
   await (0, import_promises2.chmod)(shimPath, 493);
   console.log(`Wrote command shim: ${shimPath}`);
 }
+async function removeCommandShim(dryRun) {
+  const shimPath = (0, import_node_path4.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const content = await readFileIfExists(shimPath);
+  if (content === void 0) {
+    console.log(`Already absent: ${shimPath}`);
+    return;
+  }
+  if (!isManagedCommandShim(content)) {
+    console.log(`WARN not removing unmanaged command shim: ${shimPath}`);
+    return;
+  }
+  await removePath(shimPath, "command shim", dryRun);
+}
 async function installUserAgentInstructions(dryRun) {
   const block = await renderUserAgentInstructionsBlock();
   for (const target of USER_AGENT_INSTRUCTION_TARGETS) {
@@ -6979,10 +7026,39 @@ async function installUserAgentInstructions(dryRun) {
       continue;
     }
     await ensureDirectory((0, import_node_path2.dirname)(targetPath), false);
-    await (0, import_promises9.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    await (0, import_promises10.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(currentContent === void 0 ? `Wrote ${targetPath}` : `Updated ${targetPath}`);
   }
 }
+async function removeUserAgentInstructions(dryRun) {
+  for (const target of USER_AGENT_INSTRUCTION_TARGETS) {
+    const targetPath = expandPath(target.path);
+    const currentContent = await readFileIfExists(targetPath);
+    if (currentContent === void 0) {
+      console.log(`Already absent: ${targetPath}`);
+      continue;
+    }
+    const nextContent = removeManagedBlock(currentContent);
+    if (nextContent === void 0) {
+      console.log(`WARN ${targetPath} has partial threadnote markers; not modifying it`);
+      continue;
+    }
+    if (nextContent === currentContent) {
+      console.log(`No threadnote block found: ${targetPath}`);
+      continue;
+    }
+    if (nextContent.trim().length === 0) {
+      await removePath(targetPath, target.label, dryRun);
+      continue;
+    }
+    if (dryRun) {
+      console.log(`Would update ${targetPath}`);
+      continue;
+    }
+    await (0, import_promises10.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    console.log(`Updated ${targetPath}`);
+  }
+}
 async function renderUserAgentInstructionsBlock() {
   const instructions = (await (0, import_promises5.readFile)((0, import_node_path4.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
   return `${USER_INSTRUCTIONS_START_MARKER}
@@ -7010,6 +7086,20 @@ function upsertManagedBlock(content, block) {
   }
   return joinMarkdownSections([content.trimEnd(), block]);
 }
+function removeManagedBlock(content) {
+  const startIndex = content.indexOf(USER_INSTRUCTIONS_START_MARKER);
+  const endIndex = content.indexOf(USER_INSTRUCTIONS_END_MARKER);
+  if (startIndex === -1 !== (endIndex === -1) || endIndex < startIndex) {
+    return void 0;
+  }
+  if (startIndex === -1) {
+    return content;
+  }
+  const before = content.slice(0, startIndex).trimEnd();
+  const after = content.slice(endIndex + USER_INSTRUCTIONS_END_MARKER.length).trimStart();
+  const nextContent = joinMarkdownSections([before, after]);
+  return nextContent.trim().length > 0 ? nextContent : "";
+}
 function joinMarkdownSections(sections) {
   return `${sections.filter((section) => section.length > 0).join("\n\n")}
 `;
@@ -7059,12 +7149,44 @@ async function installLaunchAgent(config, dryRun) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(destination), false);
-  await (0, import_promises9.writeFile)(destination, rendered, "utf8");
+  await (0, import_promises10.writeFile)(destination, rendered, "utf8");
   await maybeRun(false, "launchctl", ["unload", destination], { allowFailure: true });
   await maybeRun(false, "launchctl", ["load", destination]);
   await maybeRun(false, "launchctl", ["start", LAUNCHD_LABEL]);
   console.log(`Installed and started ${LAUNCHD_LABEL}`);
 }
+async function removeLaunchAgent(dryRun) {
+  const launchAgentPath = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
+  const content = await readFileIfExists(launchAgentPath);
+  if (content === void 0) {
+    console.log(`Already absent: ${launchAgentPath}`);
+    return;
+  }
+  if (!content.includes(LAUNCHD_LABEL) || !content.includes(OPENVIKING_SERVER_COMMAND)) {
+    console.log(`WARN not removing unmanaged LaunchAgent: ${launchAgentPath}`);
+    return;
+  }
+  await removePath(launchAgentPath, "LaunchAgent", dryRun);
+}
+async function removeMcpConfigs(value, dryRun) {
+  const clients = await resolveMcpClients(value, "remove");
+  if (clients.length === 0) {
+    console.log("Skipping MCP config removal.");
+    return;
+  }
+  for (const client of clients) {
+    const command = buildMcpRemoveCommand(client, OPENVIKING_MCP_NAME);
+    await maybeRun(dryRun, command.executable, command.args, { allowFailure: true, cwd: command.cwd });
+  }
+}
+async function removeMcpSnippets(config, dryRun) {
+  await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "mcp", `${OPENVIKING_MCP_NAME}.codex.toml`), "MCP snippet", dryRun);
+  await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "mcp", `${OPENVIKING_MCP_NAME}.claude.txt`), "MCP snippet", dryRun);
+}
+async function eraseThreadnoteHome(path, dryRun) {
+  assertSafeThreadnoteHomeForErase(path);
+  await removePathIfExists(path, "THREADNOTE_HOME and all memories", dryRun);
+}
 function openVikingServerArgs(config) {
   return ["--config", (0, import_node_path4.join)(config.agentContextHome, "ov.conf"), "--host", config.host, "--port", String(config.port)];
 }
@@ -7123,7 +7245,7 @@ async function prepareSeedFile(config, candidate, dryRun) {
     return redactedPath;
   }
   await ensureDirectory((0, import_node_path2.dirname)(redactedPath), false);
-  await (0, import_promises9.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(redactedPath, 384);
   return redactedPath;
 }
@@ -7263,7 +7385,7 @@ async function storeMemory(config, memory, dryRun) {
     console.log(formatShellCommand(ov, withIdentity(config, ["add-memory", memory])));
     return;
   }
-  await (0, import_promises9.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(memoryPath, 384);
   await maybeRun(false, ov, withIdentity(config, ["add-memory", memory]));
 }
@@ -7764,14 +7886,14 @@ async function exists(path) {
 }
 async function isFile(path) {
   try {
-    return (await (0, import_promises8.stat)(path)).isFile();
+    return (await (0, import_promises9.stat)(path)).isFile();
   } catch (_err) {
     return false;
   }
 }
 async function isDirectory(path) {
   try {
-    return (await (0, import_promises8.stat)(path)).isDirectory();
+    return (await (0, import_promises9.stat)(path)).isDirectory();
   } catch (_err) {
     return false;
   }
@@ -7783,6 +7905,21 @@ async function readFileIfExists(path) {
     return void 0;
   }
 }
+async function removePathIfExists(path, label, dryRun) {
+  if (!await exists(path)) {
+    console.log(`Already absent: ${path}`);
+    return;
+  }
+  await removePath(path, label, dryRun);
+}
+async function removePath(path, label, dryRun) {
+  if (dryRun) {
+    console.log(`Would remove ${label}: ${path}`);
+    return;
+  }
+  await (0, import_promises8.rm)(path, { force: true, recursive: true });
+  console.log(`Removed ${label}: ${path}`);
+}
 function renderTemplate(template, config) {
   return template.replaceAll("{{THREADNOTE_HOME}}", config.agentContextHome).replaceAll("{{OPENVIKING_ACCOUNT}}", config.account).replaceAll("{{OPENVIKING_AGENT_ID}}", config.agentId).replaceAll("{{OPENVIKING_HOST}}", config.host).replaceAll("{{OPENVIKING_PORT}}", String(config.port)).replaceAll("{{OPENVIKING_USER}}", config.user);
 }
@@ -7818,7 +7955,7 @@ function parseClaudeMcpScope(value) {
   }
   throw new Error(`Invalid Claude MCP scope: ${value}. Expected local, project, or user.`);
 }
-async function resolveRepairMcpClients(value) {
+async function resolveMcpClients(value, action) {
   const normalized = value.trim().toLowerCase();
   if (normalized === "none" || normalized === "false" || normalized === "off") {
     return [];
@@ -7832,7 +7969,7 @@ async function resolveRepairMcpClients(value) {
   const clients = [];
   for (const client of requested) {
     if (!await findExecutable([client])) {
-      console.log(`WARN ${client} command not found; cannot repair ${client} MCP config.`);
+      console.log(`WARN ${client} command not found; cannot ${action} ${client} MCP config.`);
       continue;
     }
     if (!clients.includes(client)) {
@@ -7858,6 +7995,12 @@ function expandPath(path) {
   }
   return (0, import_node_path3.isAbsolute)(path) ? path : (0, import_node_path6.resolve)(getInvocationCwd(), path);
 }
+function assertSafeThreadnoteHomeForErase(path) {
+  const resolvedPath = (0, import_node_path6.resolve)(path);
+  if (resolvedPath === "/" || resolvedPath === (0, import_node_os.homedir)() || resolvedPath === (0, import_node_path2.dirname)((0, import_node_os.homedir)())) {
+    throw new Error(`Refusing to erase unsafe THREADNOTE_HOME: ${resolvedPath}`);
+  }
+}
 function portablePath(path) {
   const home = (0, import_node_os.homedir)();
   const resolvedPath = (0, import_node_path6.resolve)(path);

package/docs/rollout.md

@@ -21,4 +21,4 @@ Start with a local-only pilot.
 - Codex and Claude can both store and recall a shared handoff.
 - Seeding curated guidance does not import known secret patterns.
 - Fresh agents can recall repo testing guidance and discover relevant skills.
-- Removing OpenViking leaves agent configs in a known state.
+- `uninstall --dry-run` previews removal, and `uninstall` leaves memories intact unless `--erase-memories` is explicit.

package/docs/security.md

@@ -17,6 +17,7 @@
 - `mcp-install` requires `--apply` before it changes Codex or Claude config.
 - `install` updates user-level Codex and Claude instruction files through a managed Markdown block. Existing personal
   instructions outside that block are preserved.
+- `uninstall` preserves local memories by default. `--erase-memories` is required before deleting `THREADNOTE_HOME`.
 - Config files created under `THREADNOTE_HOME` are written with user-only permissions.
 
 ## Rollout Requirements

package/docs/troubleshooting.md

@@ -105,3 +105,15 @@ This is expected. Run with `--apply` after reviewing the command:
 ```bash
 threadnote mcp-install codex --apply
 ```
+
+## Uninstall Without Losing Memories
+
+Run:
+
+```bash
+threadnote uninstall --dry-run
+threadnote uninstall
+```
+
+By default, uninstall removes Threadnote-managed shims, MCP config, launchd config, and user instruction blocks while
+preserving `THREADNOTE_HOME`. To delete local OpenViking data too, pass `--erase-memories`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",