runtrim 0.1.14 → 0.1.16

package/README.md

@@ -1,243 +1,76 @@
 # RunTrim
 
-Scope the run before the agent touches your repo.
+RunTrim is the control layer for AI coding agents.
 
-RunTrim is a local-first control layer for AI coding agents. It prepares guarded prompts, monitors execution scope, checks outcomes, and keeps project memory so the next run starts with context.
+It gives Claude, Codex, Cursor, ChatGPT, and other agents project memory, scoped contracts, MCP guidance, approval flow, and finish verification before changes are accepted.
 
-## What RunTrim is
-
-RunTrim is a CLI for developers using tools like Claude Code, Codex, Cursor, and ChatGPT. It sits in front of your coding run and helps you avoid risky, oversized, or context-wasting prompts.
-
-## Why RunTrim exists
-
-AI coding runs often fail for operational reasons, not model quality:
-- tasks are too broad
-- sensitive surfaces are touched by accident
-- context is lost between sessions
-- teams repeat failed attempts without a reliable run log
-
-RunTrim adds structure before the run and continuity after the run.
-
-## Daily loop
-
-Recommended daily flow:
-
-```bash
-runtrim go "your task"
-```
-
-RunTrim prepares a guarded prompt, copies it for your agent, records the run locally, and prints the next steps.
-Paste the guarded prompt into your agent.
-Keep the local panel open:
-
-```bash
-runtrim panel --monitor
-```
-
-After edits:
-
-```bash
-runtrim check
-```
-
-If context or usage runs out:
-
-```bash
-runtrim continue --reason usage_limit
-```
-
-Guided menu when unsure:
-
-```bash
-runtrim start
-```
-
-`runtrim start` checks repo state and tells you the next safe command.
-Free includes 1 tracked local repo.
-
-Direct operator flow:
-
-```bash
-runtrim go "fix checkout redirect"
-runtrim panel --monitor
-runtrim check
-runtrim continue --reason usage_limit
-runtrim memory
-```
+Website: https://www.runtrim.com
 
 ## Install
 
-Global install for end users:
-
 ```bash
 npm install -g runtrim
-runtrim go "your task"
-```
-
-Local preview for repository development:
-
-```bash
-git clone https://github.com/michelpronkk-oss/rtrim
-cd rtrim
-npm install
-npm run runtrim -- init
-npm run runtrim -- start
 ```
 
-## CLI release checklist
-
-Before publishing to npm:
-
-1. `npm run build`
-2. `npm run verify:cli`
-3. `npm run verify:package`
-4. `npm link`
-5. `runtrim agent --help`
-6. `runtrim go "test task" --no-sync`
-7. `npm version patch`
-8. `npm publish`
-
-## What RunTrim does
-
-- audits task scope before execution
-- blocks unsafe mega-runs and suggests split-safe follow-ups
-- generates guarded prompts with explicit stop rules
-- monitors changed files during execution
-- reviews changed files, risk flags, verification debt, and next safe action after edits
-- shows current project memory, latest run state, and continuation guidance in `.runtrim/`
-
-## Core commands
+## Quickstart
 
 ```bash
-runtrim init
-runtrim go "<task>"
+cd your-project
 runtrim start
-runtrim prepare "<task>"
-runtrim panel
-runtrim panel --monitor
-runtrim check
-runtrim continue --reason usage_limit
-runtrim memory
-runtrim sync
+runtrim agent "Fix the homepage copy" --copy
+runtrim finish
 ```
 
-Advanced commands:
+## Primary flow
 
-```bash
-runtrim prepare "<task>"
-runtrim start
-runtrim panel
-runtrim panel --monitor
-runtrim check
-runtrim continue --reason usage_limit
-```
+1. `runtrim start` analyzes the project and prepares local RunTrim memory and instructions.
+2. `runtrim agent "task" --copy` creates a guarded run and handoff prompt for your coding agent.
+3. Agent completes the task inside contract scope.
+4. `runtrim finish` verifies scope and sensitive-file safety with a clear verdict: `PASS`, `WARN`, or `BLOCKED`.
 
-## Examples
-
-Guarded prepare flow:
+If scope needs to expand safely:
 
 ```bash
-runtrim prepare "fix checkout redirect"
+runtrim approve "Allow <path or scope> for this run only"
 ```
 
-High-risk split-required flow:
+## MCP (optional)
 
 ```bash
-runtrim prepare "rewrite auth flow, middleware, database schema and billing"
+runtrim mcp instructions
+runtrim mcp config --print
+runtrim mcp start
 ```
 
-## Monitor and panel
-
-Use `runtrim panel` to open a local browser panel on localhost.
-Use `runtrim panel --monitor` to open the same local panel with live git change monitoring.
+MCP lets compatible agents use RunTrim tools like contract creation, path checks, approval suggestions, and finish guidance.
 
-It keeps local run state visible and warns when scope drifts into risky or forbidden areas.
-Quick keys in panel:
-- `p` prepare
-- `g` guard
-- `c` check
-- `m` memory
-- `r` report
-- `s` sync
-- `q` quit
+## Local-first trust model
 
-## Check
+- Free CLI runs locally.
+- Source code stays local by default.
+- RunTrim does not read env file contents.
+- Ignored `.env.local` is warned and reported, not read.
+- Sensitive tracked/changed or unignored sensitive files still block finish.
 
-Run `runtrim check` after the agent edits files.
+## Plans and sync
 
-It validates changed files, summarizes risk posture, and reports missing proof items before you continue.
+- Free: local control flow and local history.
+- Pro+: cloud sync and hosted dashboard history.
 
-## Continuation recovery
-
-When a run stops due to usage or context limits:
+## Core commands
 
 ```bash
-runtrim continue --reason usage_limit
+runtrim start
+runtrim agent "Your task" --copy
+runtrim finish
+runtrim approve "Allow <scope> for this run only"
+runtrim status
+runtrim mcp instructions
+runtrim bridge status
 ```
 
-RunTrim prepares a continuation prompt and stores continuation metadata in local memory.
-
-## Project memory
-
-`runtrim memory` shows where the project currently stands:
-- latest task and run status
-- changed files
-- missing proof
-- protected areas
-- next safe action
-
-## Sync V0 private beta
-
-Cloud sync is private beta and metadata-only.
-
-Sync can upload:
-- project name and status
-- run status and risk metadata
-- RunTrim-generated prompts
-- changed file paths
-- project memory summaries
-- timestamps and estimated savings
-
-Sync does not intentionally upload:
-- source code
-- `.env` values
-- secret file contents
+Advanced/lower-level command (still supported):
 
 ```bash
-runtrim auth set "<token>"
-runtrim config set dashboard-url https://www.runtrim.com/app
-runtrim sync
+runtrim go "Your task"
 ```
-
-## Privacy model
-
-RunTrim Free runs locally and stores state in `.runtrim`.
-Free includes 1 tracked local repo. Builder early access supports unlimited tracked repos.
-A tracked repo is one codebase with its own `.runtrim` workspace.
-
-V1 is designed so source code is not uploaded. Cloud sync stores metadata only when enabled.
-
-See:
-- https://www.runtrim.com/privacy
-- https://www.runtrim.com/security
-
-## Status
-
-RunTrim is in early V1.
-
-Free local CLI is available. Cloud sync and hosted dashboard access are private beta.
-
-## Roadmap
-
-- npm package launch hardening
-- stronger local policy presets
-- richer post-run verification workflows
-- expanded cloud memory rollout
-
-## Packaging
-
-```bash
-npm run build
-npm run build:cli
-npm pack --dry-run
-```

package/dist-cli/runtrim.cjs

@@ -10845,6 +10845,9 @@ async function syncRunsToCloud(input) {
     });
     const body = await res.json().catch(() => ({}));
     if (!res.ok || !body.ok) {
+      if (res.status === 401 || res.status === 403) {
+        return { status: "skipped_invalid_token" };
+      }
       if (markPendingRunIds && markPendingRunIds.length > 0) {
         for (const id of markPendingRunIds) updateRun(id, { pendingSync: true }, cwd);
       }
@@ -11420,18 +11423,25 @@ program.command("sync").description("Sync local run history and project memory t
       runs
     });
     if (result.status !== "synced") {
-      spinner.fail("  Sync failed.");
-      console.log("");
       if (result.status === "skipped_no_token") {
-        console.log(chalk.yellow("  No CLI token found."));
+        spinner.stop();
+        console.log("");
+        console.log(DIM("  Cloud sync not configured."));
         console.log(DIM("  Run ") + GO_ACCENT("runtrim login") + DIM(" to connect cloud sync."));
         console.log(DIM("  Local CLI still works without a token."));
       } else if (result.status === "skipped_invalid_token") {
-        console.log(chalk.yellow("  Stored token format is invalid. Re-run: runtrim login"));
+        spinner.stop();
+        console.log("");
+        console.log(DIM("  Cloud sync not configured. Run saved locally."));
+        console.log(DIM("  Re-run: runtrim login"));
       } else if (result.error) {
+        spinner.fail("  Sync failed.");
+        console.log("");
         console.log(chalk.red("  Error: ") + chalk.white(result.error));
         if (result.details) console.log(chalk.red("  Details: ") + chalk.white(result.details));
       } else {
+        spinner.fail("  Sync failed.");
+        console.log("");
         console.log(chalk.yellow("  Failed. Run saved locally. Use runtrim sync later."));
       }
       console.log("");

package/dist-cli/runtrim.js

@@ -10824,6 +10824,9 @@ async function syncRunsToCloud(input) {
     });
     const body = await res.json().catch(() => ({}));
     if (!res.ok || !body.ok) {
+      if (res.status === 401 || res.status === 403) {
+        return { status: "skipped_invalid_token" };
+      }
       if (markPendingRunIds && markPendingRunIds.length > 0) {
         for (const id of markPendingRunIds) updateRun(id, { pendingSync: true }, cwd);
       }
@@ -11399,18 +11402,25 @@ program.command("sync").description("Sync local run history and project memory t
       runs
     });
     if (result.status !== "synced") {
-      spinner.fail("  Sync failed.");
-      console.log("");
       if (result.status === "skipped_no_token") {
-        console.log(chalk.yellow("  No CLI token found."));
+        spinner.stop();
+        console.log("");
+        console.log(DIM("  Cloud sync not configured."));
         console.log(DIM("  Run ") + GO_ACCENT("runtrim login") + DIM(" to connect cloud sync."));
         console.log(DIM("  Local CLI still works without a token."));
       } else if (result.status === "skipped_invalid_token") {
-        console.log(chalk.yellow("  Stored token format is invalid. Re-run: runtrim login"));
+        spinner.stop();
+        console.log("");
+        console.log(DIM("  Cloud sync not configured. Run saved locally."));
+        console.log(DIM("  Re-run: runtrim login"));
       } else if (result.error) {
+        spinner.fail("  Sync failed.");
+        console.log("");
         console.log(chalk.red("  Error: ") + chalk.white(result.error));
         if (result.details) console.log(chalk.red("  Details: ") + chalk.white(result.details));
       } else {
+        spinner.fail("  Sync failed.");
+        console.log("");
         console.log(chalk.yellow("  Failed. Run saved locally. Use runtrim sync later."));
       }
       console.log("");

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "runtrim",
-  "version": "0.1.14",
-  "description": "CLI guard layer that scopes AI coding runs before they waste tokens.",
+  "version": "0.1.16",
+  "description": "The control layer for AI coding agents.",
   "license": "MIT",
   "author": "RunTrim",
-  "homepage": "https://runtrim.dev",
+  "homepage": "https://www.runtrim.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/michelpronkk-oss/rtrim.git"
@@ -15,11 +15,15 @@
   "keywords": [
     "cli",
     "ai-coding",
+    "coding-agents",
     "codex",
     "claude",
     "cursor",
+    "mcp",
     "developer-tools",
-    "prompt-guard"
+    "agent-control",
+    "code-safety",
+    "ai-agents"
   ],
   "bin": {
     "runtrim": "dist-cli/runtrim.cjs"