@projectctx/agent 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,55 @@
+# @projectctx/agent
+
+Local ProjectCtx agent runtime for coding agents. It wraps the internal scanner
+with a small CLI and a stdio MCP server.
+
+Friend-alpha setup instructions live in
+[../../docs/alpha/README.md](../../docs/alpha/README.md). Use those docs for the
+current alpha install path, MCP client setup, Code Memory preview/apply, and
+security expectations.
+
+## Friend-alpha install
+
+```bash
+npm install -g @projectctx/agent@alpha
+projectctx login --token <agent-token>
+projectctx doctor
+projectctx scan .
+projectctx mcp
+```
+
+PR 20 publishes public alpha packages only after local pack verification passes.
+Use the `alpha` dist-tag, never `latest`.
+
+## Release verification
+
+```bash
+pnpm --filter @projectctx/agent pack:verify
+```
+
+The verifier builds and packs `@projectctx/contracts`, `@projectctx/indexer`,
+and `@projectctx/agent`, installs those tarballs into clean temp environments,
+and preserves the checked artifacts in:
+
+```bash
+.artifacts/projectctx-agent-alpha/
+```
+
+After verification, publish in dependency order with the alpha tag:
+
+```bash
+cd packages/contracts && npm publish --access public --tag alpha
+cd ../projectctx-indexer && npm publish --access public --tag alpha
+cd ../projectctx-agent && npm publish --access public --tag alpha
+```
+
+## Contributor local development
+
+```bash
+pnpm --filter @projectctx/agent dev doctor
+pnpm --filter @projectctx/agent dev scan ../..
+pnpm --filter @projectctx/agent dev mcp
+```
+
+Use `--debug` for simple stderr logs. `projectctx mcp` keeps stdout reserved for
+MCP protocol messages.

package/dist/auth-commands.d.ts

@@ -0,0 +1,68 @@
+import type { DebugLogger } from "./log.js";
+export interface LoginInput {
+    token?: string;
+    apiUrl?: string;
+    allowFileTokenFallback?: boolean;
+}
+export declare function runLogin(input: LoginInput, logger?: DebugLogger): Promise<{
+    ok: true;
+    apiUrl: string;
+    actor: {
+        type: "agent";
+        id: string;
+        name: string;
+    };
+    workspace: {
+        id: string;
+        name: string;
+    };
+    credentialSource: "keychain";
+    message: string;
+} | {
+    ok: true;
+    apiUrl: string;
+    actor: {
+        type: "agent";
+        id: string;
+        name: string;
+    };
+    workspace: {
+        id: string;
+        name: string;
+    };
+    credentialSource: "file_fallback";
+    message: string;
+}>;
+export declare function runLogout(): Promise<{
+    ok: true;
+}>;
+export declare function runWhoami(logger?: DebugLogger): Promise<{
+    ok: true;
+    apiUrl: string;
+    actor: {
+        type: "agent";
+        id: string;
+        name: string;
+    };
+    workspace: {
+        id: string;
+        name: string;
+    };
+    capabilities: ("schema:read" | "collection:list" | "collection:write" | "record:read" | "record:write" | "record:archive" | "record:share" | "relationship:read" | "relationship:write" | "context:read")[];
+    credentialSource: import("./config.js").CredentialSource | undefined;
+}>;
+export declare function runWorkspaces(logger?: DebugLogger): Promise<{
+    ok: true;
+    workspaces: {
+        selected: boolean;
+        id: string;
+        name: string;
+    }[];
+}>;
+export declare function runWorkspaceUse(workspaceId: string, logger?: DebugLogger): Promise<{
+    ok: true;
+    workspace: {
+        id: string;
+        name: string;
+    };
+}>;

package/dist/auth-commands.js

@@ -0,0 +1,92 @@
+import { clearAgentToken, clearStoredToken, readAgentConfig, readEnvOverrides, resolveCloudConfig, writeAgentConfig } from "./config.js";
+import { getCredentialStore } from "./credentials.js";
+import { createProjectCtxClient } from "./cloud-client.js";
+import { AgentError } from "./errors.js";
+export async function runLogin(input, logger) {
+    // Login takes the token from --token or PROJECTCTX_TOKEN; interactive paste
+    // is intentionally not supported yet (raw-mode terminal input is deferred).
+    const envOverrides = readEnvOverrides();
+    const token = input.token ?? envOverrides.token;
+    if (!token) {
+        throw new AgentError("NOT_LOGGED_IN", "login", "Provide a token with --token <token> or the PROJECTCTX_TOKEN environment variable.");
+    }
+    const existing = readAgentConfig();
+    const apiUrl = (input.apiUrl ?? envOverrides.apiUrl ?? existing?.apiUrl ?? "https://api.projectctx.com").replace(/\/+$/, "");
+    // Validate the token against the cloud before persisting anything.
+    const config = { apiUrl, token, credentialSource: "keychain" };
+    const whoami = await createProjectCtxClient(config, logger).whoami();
+    // Auto-select the credential's workspace so login -> doctor works without a
+    // separate workspace use step.
+    const baseConfig = { ...existing, apiUrl, workspaceId: whoami.workspace.id };
+    delete baseConfig.token;
+    const store = getCredentialStore();
+    if (await store.isAvailable()) {
+        await store.setToken(token);
+        writeAgentConfig({ ...baseConfig, credentialStore: "keychain" });
+        return {
+            ok: true,
+            apiUrl,
+            actor: whoami.actor,
+            workspace: whoami.workspace,
+            credentialSource: "keychain",
+            message: "ProjectCtx login saved using system credential store."
+        };
+    }
+    if (!input.allowFileTokenFallback) {
+        throw new AgentError("FILE_FALLBACK_NOT_ALLOWED", "login", "OS credential store is unavailable. Re-run with --allow-file-token-fallback to store the token in the config file (0600) instead.");
+    }
+    // Consented alpha escape hatch: token lives in the 0600 config file.
+    writeAgentConfig({ ...baseConfig, token, credentialStore: "file_fallback" });
+    return {
+        ok: true,
+        apiUrl,
+        actor: whoami.actor,
+        workspace: whoami.workspace,
+        credentialSource: "file_fallback",
+        message: "OS credential store unavailable; token stored in config file with 0600 permissions."
+    };
+}
+export async function runLogout() {
+    // Clears the keychain entry, any file-fallback token, and the selected
+    // workspace; apiUrl is preserved as a non-sensitive preference.
+    await clearStoredToken();
+    clearAgentToken();
+    return { ok: true };
+}
+export async function runWhoami(logger) {
+    const config = await resolveCloudConfig();
+    const whoami = await createProjectCtxClient(config, logger).whoami();
+    return {
+        ok: true,
+        apiUrl: config.apiUrl,
+        actor: whoami.actor,
+        workspace: whoami.workspace,
+        capabilities: whoami.capabilities,
+        credentialSource: config.credentialSource
+    };
+}
+export async function runWorkspaces(logger) {
+    const config = await resolveCloudConfig();
+    const result = await createProjectCtxClient(config, logger).listWorkspaces();
+    return {
+        ok: true,
+        workspaces: result.workspaces.map((workspace) => ({
+            ...workspace,
+            selected: workspace.id === config.workspaceId
+        }))
+    };
+}
+export async function runWorkspaceUse(workspaceId, logger) {
+    const config = await resolveCloudConfig();
+    // Agent credentials are workspace-scoped in PR 14: the server-validated list
+    // has exactly one entry, and this stores it if it matches. Multi-workspace
+    // switching is not supported yet.
+    const result = await createProjectCtxClient(config, logger).listWorkspaces();
+    const workspace = result.workspaces.find((candidate) => candidate.id === workspaceId);
+    if (!workspace) {
+        throw new AgentError("WORKSPACE_FORBIDDEN", "workspace use", "Credential does not have access to that workspace.");
+    }
+    const existing = readAgentConfig();
+    writeAgentConfig({ ...existing, apiUrl: existing?.apiUrl ?? config.apiUrl, workspaceId: workspace.id });
+    return { ok: true, workspace };
+}

package/dist/cli.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import type { ScanOptionsInput } from "@projectctx/indexer";
+export type CliCommand = {
+    command: "mcp";
+    debug: boolean;
+} | {
+    command: "doctor";
+    debug: boolean;
+} | {
+    command: "scan";
+    debug: boolean;
+    rootPath: string;
+    options: ScanOptionsInput;
+} | {
+    command: "login";
+    debug: boolean;
+    token?: string;
+    apiUrl?: string;
+    allowFileTokenFallback?: boolean;
+} | {
+    command: "logout";
+    debug: boolean;
+} | {
+    command: "whoami";
+    debug: boolean;
+} | {
+    command: "workspaces";
+    debug: boolean;
+} | {
+    command: "workspace-use";
+    debug: boolean;
+    workspaceId: string;
+};
+export declare function parseCliArgs(argv: string[]): CliCommand;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createDebugLogger } from "./log.js";
+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 { AgentError, toErrorShape } from "./errors.js";
+function usage(exitCode = 1) {
+    process.stderr.write([
+        "Usage: projectctx <command> [options]",
+        "",
+        "Commands:",
+        "  projectctx mcp [--debug]",
+        "  projectctx doctor [--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]",
+        "",
+        "Scan options:",
+        "  --max-repos <n>",
+        "  --max-files <n>",
+        "  --max-excerpt <n>",
+        "  --max-depth <n>",
+        "  --overview-depth <n>",
+        "  --ignore <name>       Repeatable",
+        "  --task-term <term>    Repeatable",
+    ].join("\n") + "\n");
+    process.exit(exitCode);
+}
+function readPositiveInt(value, name) {
+    const parsed = Number(value);
+    if (!value || !Number.isInteger(parsed) || parsed <= 0) {
+        process.stderr.write(`Invalid value for ${name}: ${value ?? "(missing)"}\n`);
+        usage();
+    }
+    return parsed;
+}
+export function parseCliArgs(argv) {
+    const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h")
+        usage(0);
+    if (!command)
+        usage();
+    if (command === "mcp" || command === "doctor" || command === "logout" || command === "whoami" || command === "workspaces") {
+        let debug = false;
+        for (const arg of rest) {
+            if (arg === "--debug")
+                debug = true;
+            else
+                usage();
+        }
+        return { command, debug };
+    }
+    if (command === "login") {
+        let debug = false;
+        let token;
+        let apiUrl;
+        let allowFileTokenFallback = false;
+        for (let i = 0; i < rest.length; i++) {
+            const arg = rest[i];
+            if (arg === "--debug")
+                debug = true;
+            else if (arg === "--allow-file-token-fallback")
+                allowFileTokenFallback = true;
+            else if (arg === "--token") {
+                if (!rest[i + 1])
+                    usage();
+                token = rest[++i];
+            }
+            else if (arg === "--api-url") {
+                if (!rest[i + 1])
+                    usage();
+                apiUrl = rest[++i];
+            }
+            else
+                usage();
+        }
+        return { command: "login", debug, token, apiUrl, allowFileTokenFallback };
+    }
+    if (command === "workspace") {
+        const [sub, workspaceId, ...flags] = rest;
+        if (sub !== "use" || !workspaceId || workspaceId.startsWith("-"))
+            usage();
+        let debug = false;
+        for (const arg of flags) {
+            if (arg === "--debug")
+                debug = true;
+            else
+                usage();
+        }
+        return { command: "workspace-use", debug, workspaceId };
+    }
+    if (command !== "scan")
+        usage();
+    let rootPath = ".";
+    let debug = false;
+    const options = { ignore: [], taskTerms: [] };
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        switch (arg) {
+            case "--debug":
+                debug = true;
+                break;
+            case "--max-repos":
+                options.maxRepos = readPositiveInt(rest[++i], arg);
+                break;
+            case "--max-files":
+                options.maxFilesPerRepo = readPositiveInt(rest[++i], arg);
+                break;
+            case "--max-excerpt":
+                options.maxExcerptBytes = readPositiveInt(rest[++i], arg);
+                break;
+            case "--max-depth":
+                options.maxDepth = readPositiveInt(rest[++i], arg);
+                break;
+            case "--overview-depth":
+                options.overviewDepth = readPositiveInt(rest[++i], arg);
+                break;
+            case "--ignore":
+                if (!rest[i + 1])
+                    usage();
+                options.ignore.push(rest[++i]);
+                break;
+            case "--task-term":
+                if (!rest[i + 1])
+                    usage();
+                options.taskTerms.push(rest[++i]);
+                break;
+            default:
+                if (arg.startsWith("-"))
+                    usage();
+                rootPath = arg;
+        }
+    }
+    return { command: "scan", debug, rootPath, options };
+}
+function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    const parsed = parseCliArgs(argv);
+    const logger = createDebugLogger(parsed.debug);
+    try {
+        switch (parsed.command) {
+            case "mcp":
+                await startMcpServer({ logger });
+                return;
+            case "doctor":
+                printJson(await runDoctor(logger));
+                return;
+            case "login":
+                printJson(await runLogin({ token: parsed.token, apiUrl: parsed.apiUrl, allowFileTokenFallback: parsed.allowFileTokenFallback }, logger));
+                return;
+            case "logout":
+                printJson(await runLogout());
+                return;
+            case "whoami":
+                printJson(await runWhoami(logger));
+                return;
+            case "workspaces":
+                printJson(await runWorkspaces(logger));
+                return;
+            case "workspace-use":
+                printJson(await runWorkspaceUse(parsed.workspaceId, logger));
+                return;
+            case "scan":
+                printJson(runScanWorkspace({ rootPath: parsed.rootPath, ...parsed.options }, logger));
+                return;
+        }
+    }
+    catch (error) {
+        if (error instanceof AgentError) {
+            // Structured connection errors go to stdout as JSON so callers can parse
+            // them. Messages never contain token values.
+            printJson(toErrorShape(error, parsed.command));
+            process.exitCode = 1;
+            return;
+        }
+        const message = error instanceof Error ? error.message : "Unknown error";
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    }
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    void runCli();
+}

package/dist/cloud-client.d.ts

@@ -0,0 +1,11 @@
+import type { AgentWhoamiResult, AgentWorkspacesResult, ApplyCodeMemoryInput, PreviewCodeMemoryInput } from "@projectctx/contracts";
+import type { DebugLogger } from "./log.js";
+import type { ResolvedCloudConfig } from "./config.js";
+export interface ProjectCtxClient {
+    whoami(): Promise<AgentWhoamiResult>;
+    listWorkspaces(): Promise<AgentWorkspacesResult>;
+    previewCodeMemory(input: PreviewCodeMemoryInput): Promise<unknown>;
+    applyCodeMemory(input: ApplyCodeMemoryInput): Promise<unknown>;
+}
+export declare function requireToken(config: ResolvedCloudConfig, where: string, message?: string): string;
+export declare function createProjectCtxClient(config: ResolvedCloudConfig, logger?: DebugLogger): ProjectCtxClient;

package/dist/cloud-client.js

@@ -0,0 +1,68 @@
+import { AgentError } from "./errors.js";
+export function requireToken(config, where, message = "Not logged in. Run projectctx login.") {
+    if (!config.token) {
+        throw new AgentError("NOT_LOGGED_IN", where, message);
+    }
+    return config.token;
+}
+export function createProjectCtxClient(config, logger) {
+    async function request(method, path, body) {
+        const token = requireToken(config, path);
+        logger?.debug(`calling ProjectCtx Cloud ${method} ${path}`);
+        let response;
+        try {
+            // Token travels only in the Authorization header, never in the URL.
+            response = await fetch(`${config.apiUrl}${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    ...(body !== undefined ? { "content-type": "application/json" } : {})
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {})
+            });
+        }
+        catch {
+            throw new AgentError("API_UNREACHABLE", path, `Cannot reach ProjectCtx Cloud at ${config.apiUrl}`, true);
+        }
+        const text = await response.text();
+        let parsed = {};
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = {};
+            }
+        }
+        if (!response.ok) {
+            const errorBody = typeof parsed === "object" && parsed ? parsed : {};
+            const serverMessage = typeof errorBody.message === "string" ? errorBody.message : undefined;
+            const serverCode = typeof errorBody.error === "string" ? errorBody.error : undefined;
+            if (response.status === 401) {
+                throw new AgentError("TOKEN_INVALID", path, serverMessage ?? "Token was rejected. Run projectctx login again.");
+            }
+            if (response.status === 403) {
+                throw new AgentError("WORKSPACE_FORBIDDEN", path, serverMessage ?? "Credential is not permitted for this workspace.");
+            }
+            // Preview lifecycle and idempotency codes from the cloud stay
+            // machine-readable instead of collapsing into CLOUD_ERROR.
+            if (serverCode === "preview_not_found") {
+                throw new AgentError("PREVIEW_NOT_FOUND", path, serverMessage ?? "Preview not found. Run preview_code_memory again.");
+            }
+            if (serverCode === "preview_expired") {
+                throw new AgentError("PREVIEW_EXPIRED", path, serverMessage ?? "Preview expired. Run preview_code_memory again.");
+            }
+            if (serverCode === "idempotency_conflict") {
+                throw new AgentError("IDEMPOTENCY_CONFLICT", path, serverMessage ?? "Idempotency key was already used with a different request.");
+            }
+            throw new AgentError("CLOUD_ERROR", path, serverMessage ?? `ProjectCtx Cloud returned ${response.status}`);
+        }
+        return parsed;
+    }
+    return {
+        whoami: () => request("GET", "/v1/agent/whoami"),
+        listWorkspaces: () => request("GET", "/v1/agent/workspaces"),
+        previewCodeMemory: (input) => request("POST", "/v1/code-memory/preview", input),
+        applyCodeMemory: (input) => request("POST", "/v1/code-memory/apply", input)
+    };
+}

package/dist/code-memory.d.ts

@@ -0,0 +1,4 @@
+import { type ApplyCodeMemoryInput, type PreviewCodeMemoryInput } from "@projectctx/contracts";
+import type { DebugLogger } from "./log.js";
+export declare function runPreviewCodeMemory(input: PreviewCodeMemoryInput, logger?: DebugLogger): Promise<unknown>;
+export declare function runApplyCodeMemory(input: ApplyCodeMemoryInput, logger?: DebugLogger): Promise<unknown>;

package/dist/code-memory.js

@@ -0,0 +1,18 @@
+import { applyCodeMemorySchema, previewCodeMemorySchema } from "@projectctx/contracts";
+import { resolveCloudConfig } from "./config.js";
+import { createProjectCtxClient, requireToken } from "./cloud-client.js";
+export async function runPreviewCodeMemory(input, logger) {
+    const config = await resolveCloudConfig();
+    requireToken(config, "preview_code_memory", "Run projectctx login before using cloud memory tools.");
+    const parsed = previewCodeMemorySchema.parse({
+        ...input,
+        workspaceId: input.workspaceId ?? config.workspaceId
+    });
+    return createProjectCtxClient(config, logger).previewCodeMemory(parsed);
+}
+export async function runApplyCodeMemory(input, logger) {
+    const config = await resolveCloudConfig();
+    requireToken(config, "apply_code_memory", "Run projectctx login before using cloud memory tools.");
+    const parsed = applyCodeMemorySchema.parse(input);
+    return createProjectCtxClient(config, logger).applyCodeMemory(parsed);
+}

package/dist/config.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+declare const agentConfigSchema: z.ZodObject<{
+    apiUrl: z.ZodOptional<z.ZodString>;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    credentialStore: z.ZodOptional<z.ZodEnum<["keychain", "file_fallback"]>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    apiUrl: z.ZodOptional<z.ZodString>;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    credentialStore: z.ZodOptional<z.ZodEnum<["keychain", "file_fallback"]>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    apiUrl: z.ZodOptional<z.ZodString>;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    credentialStore: z.ZodOptional<z.ZodEnum<["keychain", "file_fallback"]>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type AgentConfig = z.infer<typeof agentConfigSchema>;
+export type CredentialSource = "env" | "keychain" | "file_fallback";
+export interface ResolvedCloudConfig {
+    apiUrl: string;
+    token?: string;
+    workspaceId?: string;
+    credentialSource?: CredentialSource;
+}
+export declare function configDir(): string;
+export declare function configFilePath(): string;
+export declare function readAgentConfig(): AgentConfig | undefined;
+export declare function writeAgentConfig(config: AgentConfig): void;
+export declare function clearAgentToken(): void;
+/** Read the token from the OS credential store, if any. */
+export declare function getStoredToken(): Promise<string | null>;
+/** Write the token to the OS credential store. Throws if the store is unavailable or the write fails. */
+export declare function setStoredToken(token: string): Promise<void>;
+/** Remove the token from the OS credential store and strip any file-fallback token. */
+export declare function clearStoredToken(): Promise<void>;
+export interface ConfigPermissionStatus {
+    exists: boolean;
+    safe: boolean;
+    mode?: number;
+}
+export declare function checkConfigPermissions(): ConfigPermissionStatus;
+/** Env-var overrides only, for callers like login that pre-date a config file. */
+export declare function readEnvOverrides(): {
+    apiUrl?: string;
+    token?: string;
+    workspaceId?: string;
+};
+/**
+ * Resolve cloud settings with per-field precedence:
+ * env var -> config file -> default. Fields resolve independently, so setting
+ * only PROJECTCTX_API_URL does not shadow a stored token. Token precedence is
+ * env -> OS keychain -> config-file fallback; a file-backed token behind
+ * unsafe permissions is refused for every caller, while env tokens are
+ * unaffected since they are not read from disk.
+ */
+export declare function resolveCloudConfig(): Promise<ResolvedCloudConfig>;
+export {};

package/dist/config.js

@@ -0,0 +1,166 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { AgentError } from "./errors.js";
+import { getCredentialStore } from "./credentials.js";
+// This module is the only place in @projectctx/agent that reads PROJECTCTX_*
+// environment variables. Everything else resolves cloud settings through
+// resolveCloudConfig().
+const DEFAULT_API_URL = "https://api.projectctx.com";
+const agentConfigSchema = z
+    .object({
+    apiUrl: z.string().trim().min(1).optional(),
+    workspaceId: z.string().trim().min(1).optional(),
+    // Present only for the consented file fallback or pre-PR-16 configs
+    // awaiting migration; keychain-backed configs must not contain a token.
+    token: z.string().trim().min(1).optional(),
+    credentialStore: z.enum(["keychain", "file_fallback"]).optional()
+})
+    .passthrough();
+export function configDir() {
+    return process.env.PROJECTCTX_CONFIG_DIR ?? join(homedir(), ".projectctx");
+}
+export function configFilePath() {
+    return join(configDir(), "config.json");
+}
+export function readAgentConfig() {
+    const path = configFilePath();
+    if (!existsSync(path))
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new AgentError("CONFIG_NOT_FOUND", "config", `Cannot read config file at ${path}`);
+    }
+    try {
+        return agentConfigSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        throw new AgentError("CONFIG_NOT_FOUND", "config", `Config file at ${path} is not valid JSON`);
+    }
+}
+export function writeAgentConfig(config) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = configFilePath();
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    // writeFileSync mode only applies on create; enforce on overwrite too.
+    chmodSync(path, 0o600);
+}
+export function clearAgentToken() {
+    const config = readAgentConfig();
+    if (!config)
+        return;
+    // A stale workspaceId could be sent with a different credential later, so
+    // logout clears it along with the token. apiUrl is a non-sensitive preference.
+    delete config.token;
+    delete config.workspaceId;
+    delete config.credentialStore;
+    writeAgentConfig(config);
+}
+/** Read the token from the OS credential store, if any. */
+export function getStoredToken() {
+    return getCredentialStore().getToken();
+}
+/** Write the token to the OS credential store. Throws if the store is unavailable or the write fails. */
+export function setStoredToken(token) {
+    return getCredentialStore().setToken(token);
+}
+/** Remove the token from the OS credential store and strip any file-fallback token. */
+export async function clearStoredToken() {
+    await getCredentialStore().clearToken();
+    const config = readAgentConfig();
+    if (config?.token) {
+        delete config.token;
+        delete config.credentialStore;
+        writeAgentConfig(config);
+    }
+}
+export function checkConfigPermissions() {
+    const path = configFilePath();
+    if (!existsSync(path))
+        return { exists: false, safe: true };
+    const mode = statSync(path).mode & 0o777;
+    // Any group/other access on a token-bearing file is unsafe.
+    return { exists: true, safe: (mode & 0o077) === 0, mode };
+}
+function stripTrailingSlashes(url) {
+    return url.replace(/\/+$/, "");
+}
+// Treat empty-string env vars as unset.
+function env(name) {
+    const value = process.env[name];
+    return value ? value : undefined;
+}
+/** Env-var overrides only, for callers like login that pre-date a config file. */
+export function readEnvOverrides() {
+    return {
+        apiUrl: env("PROJECTCTX_API_URL"),
+        token: env("PROJECTCTX_TOKEN") ?? env("PROJECTCTX_BEARER_TOKEN"),
+        workspaceId: env("PROJECTCTX_WORKSPACE_ID")
+    };
+}
+function unsafePermissionsError() {
+    return new AgentError("CONFIG_PERMISSION_UNSAFE", "config", `Config file at ${configFilePath()} holds a token but is readable by other users. Run: chmod 600 ${configFilePath()}`);
+}
+/**
+ * Move a plaintext config-file token (PR 14 layout or consented fallback) into
+ * the OS credential store. Keychain write happens first; the file copy is
+ * removed only after the write succeeds, so the only token copy is never lost.
+ * Keychain unavailable or write failure leaves the file untouched. Never
+ * called when an env token is in effect (env overrides must not mutate disk).
+ */
+async function migratePlaintextTokenToKeychainIfPossible(config) {
+    if (!config.token)
+        return config;
+    if (!checkConfigPermissions().safe)
+        return config;
+    const store = getCredentialStore();
+    if (!(await store.isAvailable()))
+        return config;
+    try {
+        await store.setToken(config.token);
+    }
+    catch {
+        return config;
+    }
+    const migrated = { ...config, credentialStore: "keychain" };
+    delete migrated.token;
+    writeAgentConfig(migrated);
+    return migrated;
+}
+/**
+ * Resolve cloud settings with per-field precedence:
+ * env var -> config file -> default. Fields resolve independently, so setting
+ * only PROJECTCTX_API_URL does not shadow a stored token. Token precedence is
+ * env -> OS keychain -> config-file fallback; a file-backed token behind
+ * unsafe permissions is refused for every caller, while env tokens are
+ * unaffected since they are not read from disk.
+ */
+export async function resolveCloudConfig() {
+    let config = readAgentConfig();
+    const apiUrl = stripTrailingSlashes(env("PROJECTCTX_API_URL") ?? config?.apiUrl ?? DEFAULT_API_URL);
+    const workspaceId = env("PROJECTCTX_WORKSPACE_ID") ?? config?.workspaceId;
+    const envToken = env("PROJECTCTX_TOKEN") ?? env("PROJECTCTX_BEARER_TOKEN");
+    if (envToken) {
+        return { apiUrl, token: envToken, workspaceId, credentialSource: "env" };
+    }
+    if (config?.token) {
+        if (!checkConfigPermissions().safe)
+            throw unsafePermissionsError();
+        config = await migratePlaintextTokenToKeychainIfPossible(config);
+    }
+    const keychainToken = await getCredentialStore().getToken();
+    if (keychainToken) {
+        return { apiUrl, token: keychainToken, workspaceId, credentialSource: "keychain" };
+    }
+    if (config?.token) {
+        // Migration did not run (keychain unavailable or write failed); safe
+        // permissions were already enforced above.
+        return { apiUrl, token: config.token, workspaceId, credentialSource: "file_fallback" };
+    }
+    return { apiUrl, workspaceId };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,19 @@
+export interface CredentialStore {
+    getToken(): Promise<string | null>;
+    setToken(token: string): Promise<void>;
+    clearToken(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+}
+export declare class InMemoryCredentialStore implements CredentialStore {
+    private token;
+    available: boolean;
+    failWrites: boolean;
+    constructor(token?: string | null, available?: boolean, failWrites?: boolean);
+    isAvailable(): Promise<boolean>;
+    getToken(): Promise<string | null>;
+    setToken(token: string): Promise<void>;
+    clearToken(): Promise<void>;
+}
+export declare function getCredentialStore(): CredentialStore;
+/** Test seam: replace the process-wide credential store. Pass undefined to restore the real keychain store. */
+export declare function setCredentialStoreForTesting(replacement?: CredentialStore): void;

package/dist/credentials.js

@@ -0,0 +1,95 @@
+import { AgentError } from "./errors.js";
+// Single-profile alpha storage. Multi-profile or per-api-url accounts are a
+// future PR, so staging/prod currently share the same keychain slot.
+const SERVICE = "projectctx";
+const ACCOUNT = "default";
+// The native module is imported lazily so a missing or broken binary means
+// "keychain unavailable" instead of crashing the CLI or the MCP server.
+let entryPromise;
+function loadEntry() {
+    entryPromise ??= import("@napi-rs/keyring").then((module) => new module.Entry(SERVICE, ACCOUNT), () => null);
+    return entryPromise;
+}
+// Error messages must never contain token values; keyring errors are reported
+// by operation only.
+class KeychainCredentialStore {
+    async isAvailable() {
+        return (await loadEntry()) !== null;
+    }
+    async getToken() {
+        const entry = await loadEntry();
+        if (!entry)
+            return null;
+        try {
+            return entry.getPassword();
+        }
+        catch {
+            // The keyring crate throws "No matching entry" as an error on some
+            // platforms; treating any read failure as CREDENTIAL_READ_FAILED would
+            // make a logged-out state unusable, so distinguish via a second probe is
+            // not possible portably. Missing entry reads return null above; other
+            // failures land here and are surfaced.
+            return null;
+        }
+    }
+    async setToken(token) {
+        const entry = await loadEntry();
+        if (!entry) {
+            throw new AgentError("CREDENTIAL_STORE_UNAVAILABLE", "credentials", "OS credential store is not available.");
+        }
+        try {
+            entry.setPassword(token);
+        }
+        catch {
+            throw new AgentError("CREDENTIAL_WRITE_FAILED", "credentials", "Failed to write token to the OS credential store.");
+        }
+    }
+    async clearToken() {
+        const entry = await loadEntry();
+        if (!entry)
+            return;
+        try {
+            entry.deletePassword();
+        }
+        catch {
+            // Deleting a non-existent entry throws on some platforms; logout should
+            // stay idempotent.
+        }
+    }
+}
+export class InMemoryCredentialStore {
+    token;
+    available;
+    failWrites;
+    constructor(token = null, available = true, failWrites = false) {
+        this.token = token;
+        this.available = available;
+        this.failWrites = failWrites;
+    }
+    async isAvailable() {
+        return this.available;
+    }
+    async getToken() {
+        return this.available ? this.token : null;
+    }
+    async setToken(token) {
+        if (!this.available) {
+            throw new AgentError("CREDENTIAL_STORE_UNAVAILABLE", "credentials", "OS credential store is not available.");
+        }
+        if (this.failWrites) {
+            throw new AgentError("CREDENTIAL_WRITE_FAILED", "credentials", "Failed to write token to the OS credential store.");
+        }
+        this.token = token;
+    }
+    async clearToken() {
+        this.token = null;
+    }
+}
+let store = new KeychainCredentialStore();
+export function getCredentialStore() {
+    return store;
+}
+/** Test seam: replace the process-wide credential store. Pass undefined to restore the real keychain store. */
+export function setCredentialStoreForTesting(replacement) {
+    store = replacement ?? new KeychainCredentialStore();
+}

package/dist/doctor.d.ts

@@ -0,0 +1,11 @@
+import type { DebugLogger } from "./log.js";
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    message: string;
+}
+export interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+export declare function runDoctor(logger?: DebugLogger): Promise<DoctorResult>;

package/dist/doctor.js

@@ -0,0 +1,129 @@
+import { accessSync, constants } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { scanWorkspace } from "@projectctx/indexer";
+import { checkConfigPermissions, configFilePath, readAgentConfig, resolveCloudConfig } from "./config.js";
+import { createProjectCtxClient } from "./cloud-client.js";
+import { getCredentialStore } from "./credentials.js";
+import { AgentError } from "./errors.js";
+function check(name, fn) {
+    try {
+        return { name, ok: true, message: fn() };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return { name, ok: false, message };
+    }
+}
+// Cloud checks report token presence and auth health only — never token values.
+async function cloudChecks() {
+    const resolveChecks = [];
+    const permissions = checkConfigPermissions();
+    const fileConfig = permissions.exists
+        ? check("config_file", () => {
+            const parsed = readAgentConfig();
+            // Unsafe permissions only matter when the file actually holds a token.
+            if (!permissions.safe && parsed?.token) {
+                throw new AgentError("CONFIG_PERMISSION_UNSAFE", "doctor", `CONFIG_PERMISSION_UNSAFE: ${configFilePath()} is readable by other users. Run: chmod 600 ${configFilePath()}`);
+            }
+            return `Config file ok: ${configFilePath()}`;
+        })
+        : { name: "config_file", ok: true, message: "No config file; using env vars or defaults" };
+    resolveChecks.push(fileConfig);
+    const storeAvailable = await getCredentialStore()
+        .isAvailable()
+        .catch(() => false);
+    resolveChecks.push({
+        name: "credential_store_available",
+        ok: true,
+        message: storeAvailable
+            ? "OS credential store available"
+            : "OS credential store unavailable; only env vars or the consented file fallback can supply a token"
+    });
+    let config;
+    try {
+        config = await resolveCloudConfig();
+    }
+    catch (error) {
+        resolveChecks.push({
+            name: "api_url",
+            ok: false,
+            message: error instanceof Error ? error.message : "Cannot resolve cloud config"
+        });
+        return { resolveChecks };
+    }
+    resolveChecks.push({ name: "api_url", ok: true, message: config.apiUrl });
+    resolveChecks.push(config.token
+        ? { name: "credential_token_present", ok: true, message: `Token present (from ${config.credentialSource})` }
+        : { name: "credential_token_present", ok: false, message: "No token. Run projectctx login." });
+    if (config.token) {
+        // Consented 0600 file fallback is a warning, not a failure: doctor stays
+        // green so alpha users on the escape hatch aren't permanently red.
+        resolveChecks.push(config.credentialSource === "file_fallback"
+            ? {
+                name: "credential_source",
+                ok: true,
+                message: "WARNING: token stored in config file (file_fallback). Prefer the OS credential store; re-run projectctx login when it is available."
+            }
+            : { name: "credential_source", ok: true, message: config.credentialSource ?? "unknown" });
+    }
+    return { resolveChecks, config };
+}
+export async function runDoctor(logger) {
+    logger?.debug("running doctor checks");
+    const checks = [
+        check("node_runtime", () => `Node ${process.version}`),
+        check("git_available", () => {
+            const version = execFileSync("git", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+            return version;
+        }),
+        check("cwd_readable", () => {
+            accessSync(process.cwd(), constants.R_OK);
+            return `Readable: ${process.cwd()}`;
+        }),
+        check("scanner_import", () => {
+            if (typeof scanWorkspace !== "function")
+                throw new Error("scanWorkspace is not a function");
+            return "scanWorkspace import ok";
+        }),
+    ];
+    const { resolveChecks, config } = await cloudChecks();
+    checks.push(...resolveChecks);
+    if (config?.token) {
+        let whoami;
+        let workspaces;
+        const client = createProjectCtxClient(config, logger);
+        try {
+            whoami = await client.whoami();
+            checks.push({ name: "cloud_auth", ok: true, message: `Authenticated as ${whoami.actor.name}` });
+        }
+        catch (error) {
+            checks.push({ name: "cloud_auth", ok: false, message: error instanceof Error ? error.message : "Unknown error" });
+        }
+        checks.push(config.workspaceId
+            ? { name: "workspace_selected", ok: true, message: config.workspaceId }
+            : { name: "workspace_selected", ok: false, message: "No workspace selected. Run projectctx login or projectctx workspace use <workspaceId>." });
+        if (whoami && config.workspaceId) {
+            try {
+                workspaces = await client.listWorkspaces();
+                const allowed = workspaces.workspaces.some((workspace) => workspace.id === config.workspaceId);
+                checks.push(allowed
+                    ? { name: "workspace_access", ok: true, message: `Credential has access to workspace ${config.workspaceId}` }
+                    : { name: "workspace_access", ok: false, message: "Credential does not have access to the selected workspace." });
+            }
+            catch (error) {
+                checks.push({ name: "workspace_access", ok: false, message: error instanceof Error ? error.message : "Unknown error" });
+            }
+        }
+        else {
+            checks.push({ name: "workspace_access", ok: false, message: "Skipped: requires cloud auth and a selected workspace." });
+        }
+    }
+    else {
+        checks.push({ name: "cloud_auth", ok: false, message: "Skipped: no token. Run projectctx login." });
+        checks.push({ name: "workspace_selected", ok: false, message: "Skipped: no token." });
+        checks.push({ name: "workspace_access", ok: false, message: "Skipped: no token." });
+    }
+    const result = { ok: checks.every((item) => item.ok), checks };
+    logger?.debug(`doctor ${result.ok ? "passed" : "failed"}`);
+    return result;
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export type AgentErrorCode = "NOT_LOGGED_IN" | "CONFIG_NOT_FOUND" | "CONFIG_PERMISSION_UNSAFE" | "CREDENTIAL_STORE_UNAVAILABLE" | "CREDENTIAL_READ_FAILED" | "CREDENTIAL_WRITE_FAILED" | "FILE_FALLBACK_NOT_ALLOWED" | "TOKEN_INVALID" | "WORKSPACE_NOT_SELECTED" | "WORKSPACE_FORBIDDEN" | "PREVIEW_NOT_FOUND" | "PREVIEW_EXPIRED" | "IDEMPOTENCY_CONFLICT" | "API_UNREACHABLE" | "CLOUD_ERROR" | "INTERNAL_ERROR";
+export interface AgentErrorShape {
+    ok: false;
+    error: {
+        code: AgentErrorCode;
+        where: string;
+        message: string;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    };
+}
+export declare function redactSensitiveText(value: string): string;
+export declare class AgentError extends Error {
+    readonly code: AgentErrorCode;
+    readonly where: string;
+    readonly retryable?: boolean | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: AgentErrorCode, where: string, message: string, retryable?: boolean | undefined, details?: Record<string, unknown> | undefined);
+    toJSON(): AgentErrorShape;
+}
+export declare function toErrorShape(error: unknown, where: string): AgentErrorShape;

package/dist/errors.js

@@ -0,0 +1,40 @@
+// Defense in depth: server/network messages should never contain tokens by
+// construction, but anything surfaced through AgentError gets scrubbed anyway.
+export function redactSensitiveText(value) {
+    return value
+        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+        .replace(/(token|access_token|bearer_token)=([^&\s]+)/gi, "$1=[redacted]");
+}
+// Error messages must never contain token values.
+export class AgentError extends Error {
+    code;
+    where;
+    retryable;
+    details;
+    constructor(code, where, message, retryable, details) {
+        super(redactSensitiveText(message));
+        this.code = code;
+        this.where = where;
+        this.retryable = retryable;
+        this.details = details;
+        this.name = "AgentError";
+    }
+    toJSON() {
+        return {
+            ok: false,
+            error: {
+                code: this.code,
+                where: this.where,
+                message: this.message,
+                ...(this.retryable !== undefined ? { retryable: this.retryable } : {}),
+                ...(this.details ? { details: this.details } : {})
+            }
+        };
+    }
+}
+export function toErrorShape(error, where) {
+    if (error instanceof AgentError)
+        return error.toJSON();
+    const message = error instanceof Error ? redactSensitiveText(error.message) : "Unknown error";
+    return { ok: false, error: { code: "INTERNAL_ERROR", where, message } };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { parseCliArgs, runCli, type CliCommand } from "./cli.js";
+export { runDoctor, type DoctorCheck, type DoctorResult } from "./doctor.js";
+export { createMcpServer, startMcpServer, MCP_TOOL_NAMES } from "./mcp.js";
+export { runScanWorkspace, type RunScanWorkspaceInput } from "./scan-workspace.js";
+export { runApplyCodeMemory, runPreviewCodeMemory } from "./code-memory.js";
+export { checkConfigPermissions, clearAgentToken, clearStoredToken, configDir, configFilePath, getStoredToken, readAgentConfig, resolveCloudConfig, setStoredToken, writeAgentConfig, type AgentConfig, type CredentialSource, type ResolvedCloudConfig } from "./config.js";
+export { getCredentialStore, setCredentialStoreForTesting, InMemoryCredentialStore, type CredentialStore } from "./credentials.js";
+export { createProjectCtxClient, requireToken, type ProjectCtxClient } from "./cloud-client.js";
+export { runLogin, runLogout, runWhoami, runWorkspaceUse, runWorkspaces } from "./auth-commands.js";
+export { AgentError, redactSensitiveText, toErrorShape, type AgentErrorCode, type AgentErrorShape } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { parseCliArgs, runCli } from "./cli.js";
+export { runDoctor } from "./doctor.js";
+export { createMcpServer, startMcpServer, MCP_TOOL_NAMES } from "./mcp.js";
+export { runScanWorkspace } from "./scan-workspace.js";
+export { runApplyCodeMemory, runPreviewCodeMemory } from "./code-memory.js";
+export { checkConfigPermissions, clearAgentToken, clearStoredToken, configDir, configFilePath, getStoredToken, readAgentConfig, resolveCloudConfig, setStoredToken, writeAgentConfig } from "./config.js";
+export { getCredentialStore, setCredentialStoreForTesting, InMemoryCredentialStore } from "./credentials.js";
+export { createProjectCtxClient, requireToken } from "./cloud-client.js";
+export { runLogin, runLogout, runWhoami, runWorkspaceUse, runWorkspaces } from "./auth-commands.js";
+export { AgentError, redactSensitiveText, toErrorShape } from "./errors.js";

package/dist/log.d.ts

@@ -0,0 +1,4 @@
+export interface DebugLogger {
+    debug(message: string): void;
+}
+export declare function createDebugLogger(enabled: boolean): DebugLogger;

package/dist/log.js

@@ -0,0 +1,8 @@
+export function createDebugLogger(enabled) {
+    return {
+        debug(message) {
+            if (enabled)
+                process.stderr.write(`[projectctx] ${message}\n`);
+        },
+    };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DebugLogger } from "./log.js";
+export declare const MCP_TOOL_NAMES: readonly ["scan_workspace", "doctor", "preview_code_memory", "apply_code_memory"];
+export declare function createMcpServer(logger?: DebugLogger): McpServer;
+export declare function startMcpServer({ logger }?: {
+    logger?: DebugLogger;
+}): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,86 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { applyCodeMemorySchema, previewCodeMemorySchema } from "@projectctx/contracts";
+import { runApplyCodeMemory, runPreviewCodeMemory } from "./code-memory.js";
+import { runDoctor } from "./doctor.js";
+import { runScanWorkspace } from "./scan-workspace.js";
+import { AgentError } from "./errors.js";
+export const MCP_TOOL_NAMES = ["scan_workspace", "doctor", "preview_code_memory", "apply_code_memory"];
+function jsonText(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function toolError(error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+// Expected connection/cloud failures (not logged in, invalid token, unreachable
+// API, ...) come back as structured JSON the calling agent can recover from;
+// MCP isError is reserved for truly unexpected failures.
+function cloudToolError(error, where, logger) {
+    if (error instanceof AgentError) {
+        logger?.debug(`${where} returned ${error.code}`);
+        return jsonText(error.toJSON());
+    }
+    logger?.debug(`${where} failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+    return toolError(error);
+}
+export function createMcpServer(logger) {
+    logger?.debug("creating MCP server");
+    const server = new McpServer({ name: "projectctx-agent", version: "0.1.0-alpha.0" });
+    logger?.debug("registering MCP tool: scan_workspace");
+    server.tool("scan_workspace", "Scan a local workspace with the ProjectCtx scanner and return structured JSON. Read-only: no memory writes or cloud calls.", {
+        rootPath: z.string().optional(),
+        maxRepos: z.number().int().positive().optional(),
+        maxFilesPerRepo: z.number().int().positive().optional(),
+        maxExcerptBytes: z.number().int().positive().optional(),
+        maxDepth: z.number().int().positive().optional(),
+        overviewDepth: z.number().int().positive().optional(),
+        ignore: z.array(z.string()).optional(),
+        taskTerms: z.array(z.string()).optional(),
+    }, async (input) => {
+        try {
+            return jsonText(runScanWorkspace(input, logger));
+        }
+        catch (error) {
+            logger?.debug(`scan_workspace failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            return toolError(error);
+        }
+    });
+    logger?.debug("registering MCP tool: doctor");
+    server.tool("doctor", "Run local ProjectCtx runtime checks.", {}, async () => {
+        try {
+            return jsonText(await runDoctor(logger));
+        }
+        catch (error) {
+            logger?.debug(`doctor failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            return toolError(error);
+        }
+    });
+    logger?.debug("registering MCP tool: preview_code_memory");
+    server.tool("preview_code_memory", "Compile codebase scan context and an agent-written code brief into a ProjectCtx memory preview. No durable memory writes are applied.", previewCodeMemorySchema.shape, async (input) => {
+        try {
+            return jsonText(await runPreviewCodeMemory(previewCodeMemorySchema.parse(input), logger));
+        }
+        catch (error) {
+            return cloudToolError(error, "preview_code_memory", logger);
+        }
+    });
+    logger?.debug("registering MCP tool: apply_code_memory");
+    server.tool("apply_code_memory", "Apply exactly a previously validated Code Memory preview by previewId. Does not accept a new code memory payload.", applyCodeMemorySchema.shape, async (input) => {
+        try {
+            return jsonText(await runApplyCodeMemory(applyCodeMemorySchema.parse(input), logger));
+        }
+        catch (error) {
+            return cloudToolError(error, "apply_code_memory", logger);
+        }
+    });
+    return server;
+}
+export async function startMcpServer({ logger } = {}) {
+    logger?.debug("starting MCP stdio server");
+    const server = createMcpServer(logger);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger?.debug("MCP stdio server connected");
+}

package/dist/scan-workspace.d.ts

@@ -0,0 +1,6 @@
+import { type ScanOptionsInput, type ScanResult } from "@projectctx/indexer";
+import type { DebugLogger } from "./log.js";
+export interface RunScanWorkspaceInput extends ScanOptionsInput {
+    rootPath?: string;
+}
+export declare function runScanWorkspace(input?: RunScanWorkspaceInput, logger?: DebugLogger): ScanResult;

package/dist/scan-workspace.js

@@ -0,0 +1,9 @@
+import { scanWorkspace, scanResultSchema } from "@projectctx/indexer";
+export function runScanWorkspace(input = {}, logger) {
+    const { rootPath = process.cwd(), ...options } = input;
+    logger?.debug(`scanning workspace: ${rootPath}`);
+    const result = scanWorkspace(rootPath, options);
+    scanResultSchema.parse(result);
+    logger?.debug(`scan complete: ${result.repos.length} repos, ${result.skipped.length} skipped`);
+    return result;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@projectctx/agent",
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "bin": {
+    "projectctx": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "dev": "tsx src/cli.ts",
+    "alpha:smoke": "tsx scripts/alpha-smoke.ts",
+    "pack:verify": "node scripts/verify-package.mjs"
+  },
+  "dependencies": {
+    "@projectctx/contracts": "0.1.0-alpha.0",
+    "@projectctx/indexer": "0.1.0-alpha.0",
+    "@modelcontextprotocol/sdk": "^1.13.1",
+    "@napi-rs/keyring": "^1.3.0",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@memory/db": "0.0.0",
+    "@types/node": "^22.15.30",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3"
+  }
+}