truthspine 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# TruthSpine MCP connector (npm)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/truthspine)](https://www.npmjs.com/package/truthspine) [![weekly downloads](https://img.shields.io/npm/dw/truthspine)](https://www.npmjs.com/package/truthspine) [![license](https://img.shields.io/npm/l/truthspine)](LICENSE)
+
+The free MCP connector for TruthSpine, the local-first project-truth app for AI agents.
+
+Stop re-explaining your project to every new AI chat. It works on your computer, with no cloud account and nothing extra to install.
+
+One checked record of what was decided, what was done, what failed and what comes next. Every connected chat checks your project before it answers, so you never re-explain it. Your project stays on your computer.
+
+This is the free connector. It needs the TruthSpine desktop app installed on the same computer: the [Microsoft Store](https://apps.microsoft.com/detail/9pbn25k75vdj) on Windows, the [Mac App Store](https://apps.apple.com/app/id6794478470) on macOS, or the AppImage from [truthspine.app](https://truthspine.app/download) on Linux.
+
+## See it
+
+![Codex in VS Code is asked what was decided for custom cake orders and answers from TruthSpine's saved record: $39.](https://truthspine.app/media/listing/truthspine-codex-demo.gif)
+
+*Codex in VS Code. Real recording, waits shortened.*
+
+![Every new chat makes me explain the entire project again. Every connected chat checks your project before it answers, so you never re-explain it.](https://truthspine.app/media/listing/truthspine-panel-1.png)
+
+![My agents drift onto old plans or the wrong project. Each chat works with its own project, and the current decisions win over old ones.](https://truthspine.app/media/listing/truthspine-panel-2.png)
+
+![Built to work where You work. 19 AI apps on Windows, 18 on Mac and Linux, and cloud agents through Remote access.](https://truthspine.app/media/listing/truthspine-panel-6.png)
+
+## Setup
+
+1. Install and open the TruthSpine app, and connect your project folder in it.
+2. Add an MCP server to your tool that runs `npx -y @timeprooflabs/truthspine-mcp --host <tool>`, started in your project folder (or add `--project <folder>`). Use your tool's name for `<tool>`. Without `--host` the connection is labelled as an agent on this computer.
+3. In a chat, say "Connect TruthSpine".
+
+Names for `--host`:
+
+- Claude Desktop: `claude-desktop`
+- Claude Code: `claude-code`
+- Codex: `codex-cli`
+- Cursor: `cursor`
+- VS Code: `vscode`
+- GitHub Copilot in VS Code: `github-copilot-vscode`
+- Cline: `cline`
+- Windsurf / Devin: `windsurf-devin`
+- OpenCode: `opencode`
+- LM Studio: `lm-studio`
+- Kiro: `kiro`
+- Google Antigravity: `antigravity`
+- JetBrains IDEs: `jetbrains`
+- Zed: `zed`
+- Hermes Agent: `hermes-agent`
+- OpenClaw: `openclaw`
+- GitHub Copilot CLI: `copilot-cli`
+- Droid: `droid`
+- Pi: `pi`
+- Gemini CLI: `gemini-cli`
+
+The TruthSpine app can also write these settings for you: open Connections and choose your tool.
+
+## Tools
+
+- `attach`: Attach this chat to the project's TruthSpine record and receive the current brief: decisions, completed work, evidence and next steps.
+- `consult`: Ask what is true about the project, what was decided and why, or what to do next. Read only.
+- `record`: Save a decision, finished work, a failure or the next step to the project's record on this computer.
+- `history`: Read what was saved recently, or confirm that a save was recorded. Read only.
+
+## Licence
+
+This connector is open source (Apache License 2.0). It needs the TruthSpine app, which you get separately.
+The connector needs no license of its own.
+On Windows, get the TruthSpine app from the Microsoft Store.
+On Mac, get the TruthSpine app from the App Store.
+On Linux, get the TruthSpine AppImage from truthspine.app.
+
+## Privacy Policy
+
+Full policy: https://truthspine.app/privacy
+
+- **What is collected:** this connector collects nothing itself. It starts the TruthSpine app installed on your computer and passes your agent's requests to it.
+- **Use and storage:** the TruthSpine app keeps your project record (decisions, completed work, evidence references and next steps) in its data folder on your computer. Project files are read on your computer and are not uploaded by TruthSpine.
+- **Third-party sharing:** none by this connector. What your agent shows or sends to its own AI provider is governed by that provider. The app contacts TimeProofLabs only for licence checks and, if you agree to it, anonymous usage counts. Purchases go through Microsoft, Apple or Stripe. Optional features you turn on, such as remote access or GitHub projects, connect only to accounts you choose.
+- **Retention:** the record stays on your computer until you delete the project or the app's data; you can download or delete it at any time from the app.
+- **Contact:** support@truthspine.app
+
+Support: https://truthspine.app/support

package/bin/truthspine-mcp.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import os from "node:os";
+import launcher from "../lib/installed-mcp-launcher.cjs";
+import contract from "../lib/claude-lifecycle-contract.cjs";
+
+const args = process.argv.slice(2);
+const option = (name) => { const index = args.indexOf(name); return index >= 0 && typeof args[index + 1] === "string" ? args[index + 1] : null; };
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write("truthspine-mcp [--host <tool>] [--project <folder>]\nStarts the TruthSpine connector for the TruthSpine app installed on this computer.\n");
+  process.exit(0);
+}
+const configuredRoot = String(option("--project") ?? process.env.TRUTHSPINE_PROJECT_ROOT ?? "").trim();
+const host = String(option("--host") ?? process.env.TRUTHSPINE_HOST_ID ?? "computer-agent").trim().toLowerCase();
+const controller = new AbortController();
+let connection;
+let startupStage = "workspace-binding";
+const stop = () => { controller.abort(); connection?.stop(1); };
+process.once("SIGINT", stop); process.once("SIGTERM", stop);
+try {
+  const unresolved = /\$\{[^}]+\}|%[A-Za-z_][A-Za-z0-9_]*%|\$env:[A-Za-z_][A-Za-z0-9_]*/i.test(configuredRoot);
+  process.env.TRUTHSPINE_PROJECT_ROOT = launcher.resolveBoundedHostWorkspace({ cwd: unresolved ? process.cwd() : configuredRoot || process.cwd(), homeDir: os.homedir() }).projectRoot;
+  process.env.TRUTHSPINE_LOCK_PROJECT_ROOT = "1";
+  process.env.TRUTHSPINE_HOST_ID = host;
+  process.env.TRUTHSPINE_LAUNCHER_HOST_ID = host;
+  delete process.env.NODE_OPTIONS; delete process.env.NODE_PATH;
+  startupStage = "installed-runtime-start";
+  process.env.TRUTHSPINE_RUNTIME_REGISTRATION_PATH = contract.defaultRuntimeRegistrationPath();
+  connection = await launcher.startInstalledMcpLauncherWithRecovery({ signal: controller.signal });
+  if (!connection?.inPlace) { const result = await connection.closed; process.exitCode = result.code; }
+} catch (error) {
+  const guidance = startupStage === "workspace-binding"
+    ? "Start it inside your project folder or pass --project <folder>. Licensing has not been checked; do not sign in or purchase to resolve this."
+    : "Install and open the TruthSpine app, connect this project in it, and check --host names your tool. This startup error alone does not establish a licensing failure.";
+  const said = (value, most) => String(value ?? "").replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/(?:[A-Za-z]:)?[\\/][^\s'"`]+/g, "[path]").trim().slice(0, most);
+  const where = String(error?.stack ?? "").split("\n").slice(1).map(frame => /at (?:async )?([\w.$<>]+) \(.*?([\w.-]+):(\d+):\d+\)$/.exec(frame.trim())).filter(Boolean).slice(0, 3).map(([, name, file, line]) => `${name} ${file}:${line}`).join(" < ");
+  const words = /purchase is not affected/i.test(String(error?.message ?? "")) ? "" : said(error?.message ?? error, 400);
+  const cause = [said(error?.code, 80), words, where && `at ${where}`].filter(Boolean).join(": ");
+  process.stderr.write(`TruthSpine startup failed at ${startupStage}. ${guidance}${cause ? ` Cause: ${cause}` : ""}\n`);
+  process.exitCode = 1;
+} finally { process.removeListener("SIGINT", stop); process.removeListener("SIGTERM", stop); }

package/lib/claude-lifecycle-contract.cjs

@@ -0,0 +1,79 @@
+"use strict";
+const crypto = require("node:crypto");
+const launcher = require("./installed-mcp-launcher.cjs");
+
+const fail = () => { throw new Error("TruthSpine could not bind this Claude session to its workspace. No automatic attachment was confirmed."); };
+// Only the host lifecycle envelope is consumed. transcript_path is never read;
+// permission_mode is never treated as a TruthSpine permission grant.
+function buildClaudeSessionStartRequest(input, { homeDir, platform = process.platform } = {}) {
+  if (typeof input !== "string" || Buffer.byteLength(input) > 65536) fail();
+  let event;
+  try { event = JSON.parse(input); } catch { fail(); }
+  if (!event || typeof event !== "object" || Array.isArray(event)
+    || event.hook_event_name !== "SessionStart"
+    || !["startup", "resume", "clear", "compact"].includes(event.source)
+    || typeof event.session_id !== "string" || !event.session_id.trim()
+    || event.session_id.length > 2048 || /[\u0000-\u001f\u007f]/.test(event.session_id)) fail();
+  const { projectRoot } = launcher.resolveBoundedHostWorkspace({ cwd: event.cwd, homeDir, platform });
+  return Object.freeze({
+    tool: "onboard_chat",
+    // Host/workspace are fixed by the transport, not overridable tool selectors.
+    // Older catalogs reject identityMode before tools/call, preventing silent
+    // fallback to the old per-attachment/title-derived chat identity.
+    arguments: Object.freeze({ hostChatId: event.session_id, identityMode: "host-thread" }),
+    projectRoot,
+    sessionIdHash: crypto.createHash("sha256").update(event.session_id).digest("hex")
+  });
+}
+
+function formatClaudeSessionStartResult(request, result) {
+  const metrics = result?.metrics;
+  if (!request || request.tool !== "onboard_chat"
+    || result?.project?.projectRoot !== request.projectRoot
+    || result?.binding?.hostSurface !== "claude-code"
+    || result?.binding?.hostChatIdHash !== request.sessionIdHash
+    || metrics?.hostSurface !== "claude-code"
+    || typeof metrics?.label !== "string" || !/^[a-z0-9][a-z0-9_-]{0,255}$/.test(metrics.label)
+    || metrics.runId !== metrics.label || metrics.sourceRef !== metrics.label
+    || !/^[a-f0-9]{32}$/.test(metrics.chatSessionFingerprint || "")) fail();
+  const identity = [
+    "TruthSpine has returned this session's workspace-bound attachment identity.",
+    `For an explicit Attach TruthSpine request in this same host session/workspace, call attach with these exact arguments: ${JSON.stringify(request.arguments)}. Never replace them with an empty object or a guessed title/ID.`,
+    "Consult answer_guard before project-dependent answers and actions. Save meaningful work with record; do not copy another chat's identity.",
+    "These identifiers provide attribution, not owner authorization or proof that reported work is correct."
+  ].join("\n");
+  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: withProjectPacket(identity, result?.packet?.text) } };
+}
+// The session starts with the project itself (B2, Brain 2026-11-01: "every new session starts already knowing my project"
+// was true nowhere, since the hook gave only the identity): the connect reply's packet follows the identity lines. Claude
+// Code keeps a hook's text to 10,000 characters and shows only a short preview of anything longer, so the whole text stays
+// under HOOK_CONTEXT_LIMIT, the packet cut at a whole line with a pointer to the rest.
+const HOOK_CONTEXT_LIMIT = 9500;
+function withProjectPacket(identity, packet) {
+  const text = typeof packet === "string" ? packet.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").trim() : "";
+  if (!text) return identity;
+  const head = `${identity}\n\nThis project, as TruthSpine keeps it now:\n`;
+  const rest = "\n(Shortened here; consult answer_guard for the rest.)";
+  if (head.length + text.length <= HOOK_CONTEXT_LIMIT) return head + text;
+  let kept = "";
+  for (const line of text.split("\n")) {
+    if (head.length + kept.length + line.length + 1 + rest.length > HOOK_CONTEXT_LIMIT) break;
+    kept += `${kept ? "\n" : ""}${line}`;
+  }
+  return kept ? head + kept + rest : identity;
+}
+// Where the installed app records itself (the same place the app writes it). Used when a
+// public connector carries no machine-specific path; an explicit setting still wins.
+function defaultRuntimeRegistrationPath({ platform = process.platform, env = process.env,
+  homeDir = require("node:os").homedir() } = {}) {
+  const path = require("node:path");
+  const configured = String(env.TRUTHSPINE_RUNTIME_REGISTRATION_PATH || "").trim();
+  if (configured) return configured;
+  // Windows: ~\.truthspine\app, never AppData, which a Store app sees only in its private copy (shared-registration-path.js).
+  if (platform === "win32") return path.win32.join(homeDir, ".truthspine", "app", "runtime.json");
+  const home = homeDir.replace(/\\/g, "/");
+  if (platform === "darwin") return path.posix.join(home, "Library", "Application Support", "TruthSpine", "runtime.json");
+  return path.posix.join(env.XDG_CONFIG_HOME || path.posix.join(home, ".config"), "TruthSpine", "runtime.json");
+}
+
+module.exports = { buildClaudeSessionStartRequest, formatClaudeSessionStartResult, defaultRuntimeRegistrationPath };