@projectctx/agent 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -13,11 +13,38 @@ security expectations.
 ```bash
 npm install -g @projectctx/agent@alpha
 projectctx login --token <agent-token>
+projectctx connect --dry-run   # preview client wiring; drop --dry-run to apply
 projectctx doctor
 projectctx scan .
 projectctx mcp
 ```
 
+## `projectctx connect`
+
+One command wires the `project-memory` MCP into every locally installed AI
+client and installs the memory instruction blocks:
+
+- **Detects** Claude Code (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), and
+  Codex (`~/.codex/config.toml`) by config presence.
+- **Wires the MCP** per client — `claude mcp add …` when the `claude` CLI is on
+  PATH, otherwise a direct JSON merge for Claude Code; JSON merge for Cursor;
+  TOML block append for Codex.
+- **Installs instruction blocks** (from `assets/instructions/`) into
+  `~/.claude/CLAUDE.md`, `~/.cursor/rules/projectctx.mdc`, and
+  `~/.codex/AGENTS.md`, wrapped in `<!-- projectctx:begin/end -->` markers so
+  re-runs replace the block instead of appending.
+- **Prints the manual remainder** for ChatGPT / claude.ai / Claude Desktop
+  (account-side connectors — no local config file).
+
+Safety: every config file is parsed → merged → written atomically (temp +
+rename) with a timestamped `.bak-<ts>` backup, and connect warns if the target
+client appears to be running. `--dry-run` prints the full plan without touching
+disk. Re-runs are idempotent (empty diff on already-wired files).
+
+Instruction texts ship in two versions; `v1` (goal-mode) is installed today.
+Swap to `v2` (checkin-mode) by re-running `connect` after roadmap T-301 — see
+[assets/instructions/README.md](assets/instructions/README.md).
+
 PR 20 publishes public alpha packages only after local pack verification passes.
 Use the `alpha` dist-tag, never `latest`.
 

package/assets/instructions/README.md

@@ -0,0 +1,35 @@
+# ProjectCtx instruction texts (T-002)
+
+These are the bootstrap instruction blocks that `projectctx connect` (T-001)
+installs into each client's rules file. They are the entire trigger mechanism on
+clients without hooks, and the discretionary half (what to search, what to save)
+even where hooks exist. See `roadmap/tasks/T-002-bootstrap-instructions.md`.
+
+## Versioning (load-bearing)
+
+- **v1** is the installed default today. It uses **goal-mode** wording
+  (`get_context` with the session's goal) because `get_context {mode:"checkin"}`
+  FAILS Zod validation until T-301 deploys (`goal` is currently required).
+- **v2** uses **checkin-mode** wording. Swap it in by re-running
+  `projectctx connect` *after T-301 ships*. The `<!-- projectctx:begin/end -->`
+  markers make the swap a clean replace, not an append.
+
+Never ship both versions into one file — the two first sentences contradict.
+
+To move the default from v1 to v2, change `INSTRUCTION_VERSION` in
+`src/connect.ts` (currently `"v1"`).
+
+## Files
+
+| Client | File(s) | Installed into |
+|--------|---------|----------------|
+| Claude Code | `claude-code.v1.md` / `.v2.md` | `~/.claude/CLAUDE.md` |
+| Cursor | `cursor.v1.md` / `.v2.md` | `~/.cursor/rules/projectctx.mdc` (with frontmatter) |
+| Codex | `codex.v1.md` / `.v2.md` | `~/.codex/AGENTS.md` |
+| ChatGPT / claude.ai | `chatgpt-claudeai.v1.md` / `.v2.md` | pasted manually (custom instructions) |
+
+The Cursor `.mdc` frontmatter (`description` + `alwaysApply: true`) is written by
+`connect` outside the marker block, since frontmatter must sit at the file top.
+
+The ChatGPT / claude.ai text is printed as part of the manual remainder — those
+connectors are account-side (settings UIs), not local config files.

package/assets/instructions/chatgpt-claudeai.v1.md

@@ -0,0 +1,6 @@
+I use a personal memory service (project-memory connector). At the start of
+a conversation, call get_context with this conversation's goal and use it as
+background about me. Search it whenever a topic from its memory map comes up or I
+reference past work. Save important decisions and learnings before we finish;
+update existing records rather than duplicating. Don't save trivia. If asked
+what you remember about me, answer from get_context and searches — don't guess.

package/assets/instructions/chatgpt-claudeai.v2.md

@@ -0,0 +1,6 @@
+I use a personal memory service (project-memory connector). At the start of
+a conversation, call get_context with mode "checkin" and use it as background
+about me. Search it whenever a topic from its memory map comes up or I
+reference past work. Save important decisions and learnings before we finish;
+update existing records rather than duplicating. Don't save trivia. If asked
+what you remember about me, answer from checkin and searches — don't guess.

package/assets/instructions/claude-code.v1.md

@@ -0,0 +1,15 @@
+## Memory (project-memory MCP)
+
+At session start, call get_context on project-memory with this session's goal
+and treat the result as background truth about me and my work.
+
+During the session, search memory before assuming or asking when a topic
+matching any collection in the returned memory map comes up, or when I
+reference past work, a decision, or "what we discussed" — and before saying
+something doesn't exist.
+
+Before the session ends — or right after any significant decision — save
+durable outcomes: decisions and why, learnings that outlive this session,
+corrections I gave you. Prefer updating existing records (via
+preview_memory_changes upserts) over creating new ones (save_memory).
+Never save session-local trivia.

package/assets/instructions/claude-code.v2.md

@@ -0,0 +1,15 @@
+## Memory (project-memory MCP)
+
+At session start, call get_context with {mode: "checkin"} once and treat
+the result as background truth about me and my work.
+
+During the session, search memory before assuming or asking when a topic
+matching any collection in the checkin map comes up, or when I reference
+past work, a decision, or "what we discussed" — and before saying
+something doesn't exist.
+
+Before the session ends — or right after any significant decision — save
+durable outcomes: decisions and why, learnings that outlive this session,
+corrections I gave you. Prefer updating existing records (via
+preview_memory_changes upserts) over creating new ones (save_memory).
+Never save session-local trivia.

package/assets/instructions/codex.v1.md

@@ -0,0 +1,10 @@
+## Memory (project-memory MCP)
+
+At session start, call get_context on project-memory with this session's goal;
+treat the result as background truth about me and my work. Search memory before
+assuming or asking when a topic from the returned memory map comes up, when I
+reference past work or a decision, or before saying something doesn't exist.
+Before finishing — or right after a significant decision — save durable outcomes
+(decisions and why, lasting learnings, corrections I gave). Prefer updating
+existing records (preview_memory_changes upserts) over new ones (save_memory).
+Never save session-local trivia.

package/assets/instructions/codex.v2.md

@@ -0,0 +1,10 @@
+## Memory (project-memory MCP)
+
+At session start, call get_context with {mode: "checkin"} once; treat the result
+as background truth about me and my work. Search memory before assuming or asking
+when a topic from the checkin map comes up, when I reference past work or a
+decision, or before saying something doesn't exist. Before finishing — or right
+after a significant decision — save durable outcomes (decisions and why, lasting
+learnings, corrections I gave). Prefer updating existing records
+(preview_memory_changes upserts) over new ones (save_memory). Never save
+session-local trivia.

package/assets/instructions/cursor.v1.md

@@ -0,0 +1,10 @@
+## Memory (project-memory MCP)
+
+At session start, call get_context on project-memory with this session's goal;
+treat the result as background truth about me and my work. Search memory before
+assuming or asking when a topic from the returned memory map comes up, when I
+reference past work or a decision, or before saying something doesn't exist.
+Before finishing — or right after a significant decision — save durable outcomes
+(decisions and why, lasting learnings, corrections I gave). Prefer updating
+existing records (preview_memory_changes upserts) over new ones (save_memory).
+Never save session-local trivia.

package/assets/instructions/cursor.v2.md

@@ -0,0 +1,10 @@
+## Memory (project-memory MCP)
+
+At session start, call get_context with {mode: "checkin"} once; treat the result
+as background truth about me and my work. Search memory before assuming or asking
+when a topic from the checkin map comes up, when I reference past work or a
+decision, or before saying something doesn't exist. Before finishing — or right
+after a significant decision — save durable outcomes (decisions and why, lasting
+learnings, corrections I gave). Prefer updating existing records
+(preview_memory_changes upserts) over new ones (save_memory). Never save
+session-local trivia.

package/dist/cli.d.ts

@@ -6,6 +6,10 @@ export type CliCommand = {
 } | {
     command: "doctor";
     debug: boolean;
+} | {
+    command: "connect";
+    debug: boolean;
+    dryRun: boolean;
 } | {
     command: "scan";
     debug: boolean;
@@ -30,6 +34,29 @@ export type CliCommand = {
     command: "workspace-use";
     debug: boolean;
     workspaceId: string;
+} | {
+    command: "token-create";
+    debug: boolean;
+    scopes: string[];
+    name?: string;
+    authToken?: string;
+    expiresInSeconds?: number;
+    workspaceId?: string;
+    apiUrl?: string;
+    noStore: boolean;
+} | {
+    command: "token-list";
+    debug: boolean;
+    authToken?: string;
+    workspaceId?: string;
+    apiUrl?: string;
+} | {
+    command: "token-revoke";
+    debug: boolean;
+    credentialId: string;
+    authToken?: string;
+    workspaceId?: string;
+    apiUrl?: string;
 };
 export declare function parseCliArgs(argv: string[]): CliCommand;
 export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -6,6 +6,8 @@ import { runDoctor } from "./doctor.js";
 import { runScanWorkspace } from "./scan-workspace.js";
 import { startMcpServer } from "./mcp.js";
 import { runLogin, runLogout, runWhoami, runWorkspaceUse, runWorkspaces } from "./auth-commands.js";
+import { runConnect, formatConnectOutput } from "./connect.js";
+import { runTokenCreate, runTokenList, runTokenRevoke } from "./token-commands.js";
 import { AgentError, toErrorShape } from "./errors.js";
 function usage(exitCode = 1) {
     process.stderr.write([
@@ -14,12 +16,16 @@ function usage(exitCode = 1) {
         "Commands:",
         "  projectctx mcp [--debug]",
         "  projectctx doctor [--debug]",
+        "  projectctx connect [--dry-run] [--debug]",
         "  projectctx scan [rootPath] [options]",
         "  projectctx login [--token <token>] [--api-url <url>] [--allow-file-token-fallback] [--debug]",
         "  projectctx logout [--debug]",
         "  projectctx whoami [--debug]",
         "  projectctx workspaces [--debug]",
         "  projectctx workspace use <workspaceId> [--debug]",
+        "  projectctx token create --scopes <a,b> [--name <n>] [--auth-token <t>] [--expires-in-days <n>] [--workspace <id>] [--no-store] [--debug]",
+        "  projectctx token list [--auth-token <t>] [--workspace <id>] [--debug]",
+        "  projectctx token revoke <credentialId> [--auth-token <t>] [--workspace <id>] [--debug]",
         "",
         "Scan options:",
         "  --max-repos <n>",
@@ -56,6 +62,19 @@ export function parseCliArgs(argv) {
         }
         return { command, debug };
     }
+    if (command === "connect") {
+        let debug = false;
+        let dryRun = false;
+        for (const arg of rest) {
+            if (arg === "--debug")
+                debug = true;
+            else if (arg === "--dry-run")
+                dryRun = true;
+            else
+                usage();
+        }
+        return { command: "connect", debug, dryRun };
+    }
     if (command === "login") {
         let debug = false;
         let token;
@@ -82,6 +101,74 @@ export function parseCliArgs(argv) {
         }
         return { command: "login", debug, token, apiUrl, allowFileTokenFallback };
     }
+    if (command === "token") {
+        const [sub, ...flags] = rest;
+        if (sub !== "create" && sub !== "list" && sub !== "revoke")
+            usage();
+        let debug = false;
+        let authToken;
+        let workspaceId;
+        let apiUrl;
+        let name;
+        let scopes = [];
+        let expiresInSeconds;
+        let noStore = false;
+        let credentialId;
+        for (let i = 0; i < flags.length; i++) {
+            const arg = flags[i];
+            if (arg === "--debug")
+                debug = true;
+            else if (arg === "--no-store")
+                noStore = true;
+            else if (arg === "--auth-token") {
+                if (!flags[i + 1])
+                    usage();
+                authToken = flags[++i];
+            }
+            else if (arg === "--workspace") {
+                if (!flags[i + 1])
+                    usage();
+                workspaceId = flags[++i];
+            }
+            else if (arg === "--api-url") {
+                if (!flags[i + 1])
+                    usage();
+                apiUrl = flags[++i];
+            }
+            else if (arg === "--name") {
+                if (!flags[i + 1])
+                    usage();
+                name = flags[++i];
+            }
+            else if (arg === "--scopes" || arg === "--scope") {
+                if (!flags[i + 1])
+                    usage();
+                // Accept comma-separated or repeated flags.
+                for (const value of flags[++i].split(",")) {
+                    const trimmed = value.trim();
+                    if (trimmed)
+                        scopes.push(trimmed);
+                }
+            }
+            else if (arg === "--expires-in-days") {
+                if (!flags[i + 1])
+                    usage();
+                expiresInSeconds = readPositiveInt(flags[++i], arg) * 24 * 60 * 60;
+            }
+            else if (!arg.startsWith("-") && sub === "revoke" && !credentialId) {
+                credentialId = arg;
+            }
+            else
+                usage();
+        }
+        if (sub === "create")
+            return { command: "token-create", debug, scopes, name, authToken, expiresInSeconds, workspaceId, apiUrl, noStore };
+        if (sub === "list")
+            return { command: "token-list", debug, authToken, workspaceId, apiUrl };
+        if (!credentialId)
+            usage();
+        return { command: "token-revoke", debug, credentialId, authToken, workspaceId, apiUrl };
+    }
     if (command === "workspace") {
         const [sub, workspaceId, ...flags] = rest;
         if (sub !== "use" || !workspaceId || workspaceId.startsWith("-"))
@@ -153,6 +240,14 @@ export async function runCli(argv = process.argv.slice(2)) {
             case "doctor":
                 printJson(await runDoctor(logger));
                 return;
+            case "connect": {
+                // Onboarding copy is human-readable, not JSON. The real run shells out
+                // to `claude mcp add` when available (runCliCommands: true); --dry-run
+                // never writes or shells out.
+                const result = runConnect({ dryRun: parsed.dryRun, runCliCommands: !parsed.dryRun, logger });
+                process.stdout.write(formatConnectOutput(result));
+                return;
+            }
             case "login":
                 printJson(await runLogin({ token: parsed.token, apiUrl: parsed.apiUrl, allowFileTokenFallback: parsed.allowFileTokenFallback }, logger));
                 return;
@@ -168,6 +263,28 @@ export async function runCli(argv = process.argv.slice(2)) {
             case "workspace-use":
                 printJson(await runWorkspaceUse(parsed.workspaceId, logger));
                 return;
+            case "token-create":
+                printJson(await runTokenCreate({
+                    scopes: parsed.scopes,
+                    name: parsed.name,
+                    authToken: parsed.authToken,
+                    expiresInSeconds: parsed.expiresInSeconds,
+                    workspaceId: parsed.workspaceId,
+                    apiUrl: parsed.apiUrl,
+                    store: !parsed.noStore
+                }, logger));
+                return;
+            case "token-list":
+                printJson(await runTokenList({ authToken: parsed.authToken, workspaceId: parsed.workspaceId, apiUrl: parsed.apiUrl }, logger));
+                return;
+            case "token-revoke":
+                printJson(await runTokenRevoke({
+                    credentialId: parsed.credentialId,
+                    authToken: parsed.authToken,
+                    workspaceId: parsed.workspaceId,
+                    apiUrl: parsed.apiUrl
+                }, logger));
+                return;
             case "scan":
                 printJson(runScanWorkspace({ rootPath: parsed.rootPath, ...parsed.options }, logger));
                 return;

package/dist/connect.d.ts

@@ -0,0 +1,101 @@
+import type { DebugLogger } from "./log.js";
+export declare const MCP_SERVER_NAME = "project-memory";
+export declare const MCP_URL = "https://projectctx.com/mcp";
+export declare const INSTRUCTION_VERSION: "v1" | "v2";
+export type ClientId = "claude-code" | "cursor" | "codex";
+export interface FileChange {
+    path: string;
+    kind: "mcp-config" | "instructions";
+    before: string | null;
+    after: string;
+    changed: boolean;
+    note?: string;
+}
+export interface ClientPlan {
+    client: ClientId;
+    label: string;
+    detected: boolean;
+    cliCommand?: {
+        argv: string[];
+        description: string;
+    };
+    changes: FileChange[];
+    warnings: string[];
+}
+export interface ConnectPlan {
+    dryRun: boolean;
+    home: string;
+    instructionVersion: "v1" | "v2";
+    clients: ClientPlan[];
+    manualRemainder: string;
+}
+export interface ConnectResult extends ConnectPlan {
+    applied: boolean;
+}
+interface ConnectPaths {
+    home: string;
+    claudeJson: string;
+    claudeMd: string;
+    cursorMcp: string;
+    cursorRules: string;
+    codexToml: string;
+    codexAgents: string;
+}
+export declare function connectPaths(home?: string): ConnectPaths;
+export declare function readManualRemainderText(version: "v1" | "v2"): string;
+/**
+ * Insert or replace the projectctx marker block in a markdown-ish file. Content
+ * outside the markers is preserved verbatim. Re-running with the same body is a
+ * no-op (byte-identical output), which is what makes connect idempotent.
+ */
+export declare function upsertMarkerBlock(existing: string | null, body: string): string;
+export declare function buildCursorMdc(existing: string | null, body: string): string;
+interface JsonMergeResult {
+    after: string;
+    changed: boolean;
+}
+export declare function mergeMcpServersJson(existing: string | null, entry: Record<string, unknown>): JsonMergeResult;
+export declare function upsertCodexToml(existing: string | null): JsonMergeResult;
+/**
+ * Write `content` to `path` atomically: back up any existing file to
+ * `<target>.bak-<timestamp>`, write to a temp file in the same directory, then
+ * rename over the target (atomic on POSIX). The temp+rename means a crash
+ * mid-write never leaves a truncated config.
+ *
+ * Symlinked configs (dotfiles setups) are followed: the write and backup act on
+ * the resolved real path, so the link stays intact and the linked target gets
+ * the new content. Renaming over the link path itself would silently replace
+ * the symlink with a regular file and leave the real target stale (review
+ * finding S1).
+ */
+export declare function atomicWriteWithBackup(path: string, content: string): {
+    backupPath?: string;
+};
+export declare function buildConnectPlan(opts?: {
+    home?: string;
+    version?: "v1" | "v2";
+    logger?: DebugLogger;
+}): ConnectPlan;
+export interface RunConnectOptions {
+    dryRun?: boolean;
+    home?: string;
+    version?: "v1" | "v2";
+    runCliCommands?: boolean;
+    logger?: DebugLogger;
+}
+export declare function runConnect(opts?: RunConnectOptions): ConnectResult;
+export interface ClientConfigStatus {
+    client: ClientId;
+    label: string;
+    configPath: string;
+    configExists: boolean;
+    mcpConfigured: boolean;
+}
+export declare function inspectClientConfigs(home?: string): ClientConfigStatus[];
+/**
+ * Render the plan as product-grade terminal copy. Doubles as onboarding, so it
+ * names every file it would touch, flags detected-vs-not, and prints the manual
+ * remainder. In dry-run it says nothing was written.
+ */
+export declare function formatConnectOutput(result: ConnectResult): string;
+export {};